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.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.
Create a service account
1
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.2
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.3
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.
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.
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: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 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
1
Create a replacement
Create a new key on the same service account and save it in your secret manager.
2
Update the client
Replace the old token in the application, pipeline, or MCP client. Verify that requests succeed with the new key.
3
Revoke the old key
Revoke the old key from the account’s details and confirm Revoke. Subsequent requests with that token fail authentication.
Disable or delete an account
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
I cannot see or manage service accounts
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.
My key returns 403 Forbidden
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.I cannot disable or delete Traversal Automation
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.