Skip to main content
The Traversal API is available to all users. Authenticate your requests with an API key, which you can create yourself from the Traversal web app.

​
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

Traversal displays the key in a modal. This is your only chance to copy it — once you dismiss the modal, the key cannot be retrieved again.Store it in a secure secret manager (1Password, AWS Secrets Manager, Vault, etc.) before closing the dialog.
API keys are shown once. If you lose a key, you’ll need to create a new one and revoke the old.

​
Use the key

Send the key as a bearer token in the Authorization header: 
Authorization: Bearer trv_ak_your_api_key_here
Each key is bound to the user who created it and their organization, and inherits that user’s role. Most endpoints require the member role, but a few (e.g., GET /v1/sessions) require admin — see the per-endpoint Required roles table in Sessions API.
ConditionResponse
Missing, invalid, or revoked token401 Unauthorized
V1 API not enabled for the organization, or insufficient role for the endpoint403 Forbidden

​
Key hygiene

  • Name keys descriptively so you can identify which system uses them.
  • Use separate keys per environment or service (e.g., one for CI, one for a local script). This limits blast radius and makes revocation surgical.
  • Rotate regularly and whenever someone with access leaves the team.
  • Never commit keys to 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 Settings > API Keys. Revocation takes effect immediately — subsequent requests using the key return 401 Unauthorized.