> ## 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.

# Service accounts

> Create organization-owned identities for API and MCP clients, manage their keys, and review their activity.

Service accounts give your scripts, pipelines, and MCP clients an identity owned by your organization. Requests and investigations belong to the service account, even when a different administrator creates or rotates its API keys.

Use a service account for a shared integration or unattended workflow. Use a [personal API key](/api/authentication#create-an-api-key) when a client should act as you.

| | Personal API key | Service-account API key |
| - | - | - |
| Identity | The user who owns the key | The service account |
| Permissions | The user's current role | The service account's current role |
| Management | The key's owner | Organization administrators |
| Typical use | Your local tools and scripts | Shared MCP clients, CI pipelines, and scheduled scripts |

## Before you start

You must be an organization **Admin** to create and manage service accounts and their keys. Sign in to the web app and open **[Settings → Account management → Service accounts](https://app.traversal.com/settings/account-management/service-accounts)**.

<Note>
  If you use a dedicated deployment, open the same settings in your organization's app. If **Account management** is not available to your administrator, contact Traversal to enable it for your deployment.
</Note>

Service-account keys currently work with the [Sessions API](/api/sessions) and [Traversal MCP](/using-traversal/mcp). Use a personal API key for the [Knowledge Files API](/api/knowledge-files) and the [Alert Intelligence API](/api/alert-intelligence).

## Create a service account

<Steps>
  <Step title="Name the account">
    On the **Service accounts** tab, click **New service account**. Enter a name that describes the workflow, such as `ci-incident-investigations` or `shared-mcp-client`, then click **Continue**.

    Account names must be unique within your organization.
  </Step>

  <Step title="Create its first key">
    Enter a **Key name**, such as `production-ci`, and click **Create**. The web app creates the account with a **Member** role and issues its first API key.
  </Step>

  <Step title="Save the key">
    Copy the token into your secret manager. The token is shown only once; you cannot retrieve it after closing the dialog.

    Confirm that you have saved the key, then click **Done** to open the account's details.
  </Step>
</Steps>

<Tip>
  Give each application or environment its own named key. You can rotate or revoke one client's key without changing the identity used by other clients of the same account.
</Tip>

## Permissions

Service accounts are limited to their own organization. They authenticate with API keys and do not sign in to the web app or manage users, roles, accounts, or credentials on their own.

Traversal checks the account's current role on each authenticated request. Its keys do not inherit the permissions of the administrator who created them.

| Role | Access |
| - | - |
| **Member** | Create investigations, retrieve sessions in the organization, and send follow-ups to sessions the account owns through the Sessions API or MCP. |
| **Admin** | Member access plus Admin-only endpoints, including `GET /v1/sessions` for organization-wide API session listing. |

Accounts created in the web app start as **Member**. The account list shows each account's role. If your workflow needs an Admin-only endpoint, contact Traversal to configure the appropriate role.

## Use the key

Store the token in an environment variable or inject it from your secret manager. Send it in the same bearer header used for personal keys:

```http theme={null}
Authorization: Bearer YOUR_SERVICE_ACCOUNT_API_KEY
```

For example, create an investigation through the Sessions API:

```bash theme={null}
curl -X POST https://api.traversal.com/v1/sessions \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Investigate elevated checkout latency in the last 30 minutes",
    "idempotency_key": "checkout-latency-2026-10-07"
  }'
```

For a dedicated deployment, use your organization's API base URL. See [API authentication](/api/authentication) and [MCP setup](/using-traversal/mcp#setup) for client configuration.

### Session ownership

All keys for an account act as the same identity. If you rotate a key, the replacement key can continue that account's investigations and send follow-ups to its existing sessions.

A key for a different service account acts as a different identity. Being in the same organization does not grant it permission to send follow-ups to another account's sessions. See [Sessions API](/api/sessions#required-roles) for endpoint permissions.

## Manage API keys

Open a service account to view its keys. Each key shows safe metadata such as its name, prefix, creator, creation date, and last use. The full token is never shown again.

To add another key, click **Create key**, enter a name, click **Create**, and save the new token before closing the dialog. Key names must be unique among that account's active keys.

### Rotate a key

<Steps>
  <Step title="Create a replacement">
    Create a new key on the same service account and save it in your secret manager.
  </Step>

  <Step title="Update the client">
    Replace the old token in the application, pipeline, or MCP client. Verify that requests succeed with the new key.
  </Step>

  <Step title="Revoke the old key">
    Revoke the old key from the account's details and confirm **Revoke**. Subsequent requests with that token fail authentication.
  </Step>
</Steps>

Revocation is permanent. Revoked keys remain visible under **Revoked API keys** so you can review their metadata. If you lose a token, create a replacement and revoke the lost key.

## Disable or delete an account

| Action | Effect | Reversible? |
| - | - | - |
| **Revoke a key** | Rejects requests made with that key. Other keys for the account keep working. | No. Create a replacement key. |
| **Disable** | Rejects authentication for every key belonging to the account. The account and key records remain. | Yes. Click **Enable** to restore access for unrevoked keys. |
| **Delete** | Removes the account from the active list and prevents it from authenticating. Historical sessions and audit records remain. | No. |

### Disable temporarily

Open the account, click **Disable**, and confirm **Disable account**. To restore access, open the disabled account and click **Enable**.

Disabling an account does not revoke its keys. Re-enabling it does not restore keys you have separately revoked. To halt an investigation already running, stop that investigation separately.

### Delete permanently

Open the account and click **Delete**. If it has active keys, the dialog asks you to revoke them first and offers **Disable** as a temporary alternative. Once no active keys remain, type the account's name to confirm deletion.

## Review activity

The **Service accounts** list shows each account's name, status, role, and **Activity last 7d**. Activity counts sessions the account started during the last seven days; it is not a count of API requests or key usage.

You can search the list, filter by status, and click **Export** to download a CSV with account details and session counts.

Where the account-type filter is available in **Analytics**, select **Service accounts**, **Users**, or **All accounts** to review machine and human activity. Service-account investigations contribute to organization investigation usage; they are not human users.

### Audit attribution

Investigations started with a service-account key are attributed to the account. The key list separately records the administrator who created each key. Where an action appears in audit records, service-account and credential metadata identify the machine caller without exposing the token.

## The Traversal Automation default

Traversal provisions a default account named **Traversal Automation** for organization-managed automation. It is marked **Default**, keeps an **Admin** role, and cannot be disabled or deleted.

Worker and automatic-trigger attribution to service accounts is rolling out by deployment. Where enabled, newly created root Workers and automatic-trigger rules use the default account, and private-chat Workers use their parent's identity. Creating a custom account or rotating its keys does not reassign existing Workers or triggers.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I cannot see or manage service accounts">
    Confirm that you are an organization Admin and have selected the correct organization. If **Account management** is still unavailable, contact Traversal about enabling it for your deployment.
  </Accordion>

  <Accordion title="My key returns 401 Unauthorized">
    Check that you supplied the complete token in the `Authorization: Bearer` header. Verify that the key is not revoked, the account is enabled, and the account has not been deleted.

    Confirm that the endpoint supports service-account keys. The Knowledge Files and Alert Intelligence APIs currently require personal keys.
  </Accordion>

  <Accordion title="My key returns 403 Forbidden">
    Check the account's role and the endpoint's ownership requirements. A Member account cannot call `GET /v1/sessions`, and an account cannot send follow-ups to another account's sessions.

    The role of the administrator who created the key does not change the account's permissions.
  </Accordion>

  <Accordion title="I cannot disable or delete Traversal Automation">
    This account is the protected automation default. Its Admin role, enabled state, and identity are retained for Traversal-managed automation. You can disable or delete other service accounts you create.
  </Accordion>
</AccordionGroup>


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