Skip to main content
Authenticate requests with a personal API key or, for the Sessions API and MCP, a service-account API key. Use a service account for shared clients and unattended workflows. Use a personal key for your own tools and for endpoints that require a human identity, including the Knowledge Files and Alert Intelligence APIs.

​
Create an API key

1

Open API key settings

Go to Settings → API Keys in the Traversal web app.
2

Create a new key

Click Add API Key, give it a descriptive name (e.g., ci-pipeline or local-dev), and confirm.
3

Copy and store the key

Copy the key from the dialog into a secret manager such as 1Password, AWS Secrets Manager, or Vault before you close it.
Traversal shows an API key only once. If you lose a key, create a new one and revoke the old one.

​
Create a service-account API key

An organization Admin creates an account and its first key under Settings → Account management → Service accounts. To add a key to an existing account, open it and click Create key. Save the token in your secret manager before you close the dialog. See Service accounts for the full setup and rotation procedure.

​
Use the key

Send the key as a bearer token in the Authorization header:
A personal key uses its owner’s current role. A service-account key uses the account’s current role, regardless of who created the key. Both are restricted to their authenticated organization. Most Sessions endpoints require Member, but GET /v1/sessions requires Admin. Follow-up requests also require ownership of the session. See the Required roles table in Sessions API.

​
Key hygiene

  • Name keys after the system that uses them.
  • Use a separate key for each environment or service, such as one for CI and one for a local script. If a key leaks, you revoke only that one.
  • Rotate keys regularly, and whenever someone with access leaves the team.
  • Keep keys out of source control. Use environment variables or a secret manager.

​
Revoke a key

If a key is lost, leaked, or no longer needed, revoke it from its management page. Revoke personal keys under Settings → API Keys; an organization Admin revokes service-account keys from the account’s details. Revocation takes effect immediately, and later requests with the key return 401 Unauthorized. For rotation, create and deploy a replacement key before revoking the old one. Keeping the replacement on the same service account preserves its session ownership.