> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create and manage API keys to authenticate with the Traversal API.

Authenticate requests with a personal API key or, for the Sessions API and MCP, a service-account API key.

| Key type | Acts as | Where to manage it |
| - | - | - |
| Personal | The user who owns the key, with their current role | **Settings → API Keys** |
| Service account | An organization-owned account, with that account's current role | **Settings → Account management → Service accounts** (Admin only) |

Use a [service account](https://docs.traversal.com/setup/service-accounts.md) 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](https://app.traversal.com/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.

> [!WARNING]
>
> 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](https://app.traversal.com/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](https://docs.traversal.com/setup/service-accounts.md#create-a-service-account) for the full setup and rotation procedure.

## Use the key

Send the key as a bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer $TRAVERSAL_API_KEY
```

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](https://docs.traversal.com/api/sessions.md#required-roles).

| Condition | Response |
| - | - |
| Missing, invalid, or revoked token | `401 Unauthorized` |
| Service-account key for a disabled or deleted account, or on an endpoint requiring a personal key | `401 Unauthorized` |
| Insufficient role, ownership, permission, or endpoint-specific access | `403 Forbidden` |

## 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](https://app.traversal.com/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.