Authentication

Small requests to POST /v1/attributions work without an API key. Omit the Authorization header for free, best-effort keyless access. A supplied key always undergoes the normal status, scope, and billing checks; invalid keys never fall back to keyless access. Generation, raw heatmaps, and account endpoints need an API key. GET /health is public. Send your key as a Bearer token:

Authorization: Bearer tpk_live_...

curl https://api.tokenpath.ai/v1/me \
  -H "Authorization: Bearer $TOKENPATH_API_KEY"

Create a key

Sign in at platform.tokenpath.ai.
Open API keys and click Create key. Naming the key is optional.
Copy the key right away. TokenPath shows the secret only once and stores just a hash of it.

Keys look like tpk_live_ followed by a short public ID and a long secret. The dashboard lists each key by its public prefix and shows when it was last used.

Get a key from a coding agent

A coding agent can get a key for you without you copying it anywhere. Paste this into Claude Code, Cursor, or Codex:

Set up TokenPath in this project using https://tokenpath.ai/skill.md

The agent asks TokenPath for a key, which stays inactive until you approve it, and shows you a link and a six-digit code. Open the link, sign in or sign up, check that the code matches, and click Approve. The agent saves the key to your project’s .env as TOKENPATH_API_KEY. The key never appears in the browser or the chat. It shows up on the API keys page as Agent · <project folder> with both scopes, and you can revoke it there like any other key. Unapproved links expire after 15 minutes. To do this without an agent, run the same helper yourself from your project root:

curl -fsSL https://tokenpath.ai/agents/tokenpath_connect.py -o /tmp/tokenpath_connect.py
python3 /tmp/tokenpath_connect.py

Keep API keys on your server. Never ship them in browser or mobile code, commit them to a repository, or paste them into logs. Read the key from an environment variable or a secrets manager at runtime.

Scopes

Each key carries scopes that decide which endpoints it can call. Keys created in the dashboard get both scopes.

Scope	Grants access to
`attributions:write`	Keyed `POST /v1/attributions`, `POST /v1/attributions/heatmap`, `POST /v1/generate`
`usage:read`	`GET /v1/me`, `GET /v1/me/credits`, `GET /v1/me/usage`

A request with a key that lacks the scope fails with 403 missing_scope. details.missing_scopes lists what is missing:

{
  "error": {
    "code": "missing_scope",
    "message": "API key is missing a required scope.",
    "details": { "missing_scopes": ["attributions:write"] },
    "request_id": "req_4f1c9a..."
  }
}

Revoke and rotate keys

To revoke a key, click Revoke next to it in the dashboard. Requests that use it fail with 403 api_key_inactive straight away. To rotate without downtime, create a new key, deploy it, confirm traffic has moved (the old key’s Last used time stops changing), and then revoke the old key.

Authentication errors

Status	Code	Meaning
`401`	`missing_api_key`	A protected endpoint needs a key, or keyless attribution is temporarily disabled.
`401`	`invalid_authorization_header`	The header is not in `Bearer <key>` form.
`401`	`invalid_api_key`	The key is malformed, unknown, or its secret does not match.
`403`	`api_key_inactive`	The key has been revoked.
`403`	`account_suspended`	The account that owns the key is not active. Email [email protected].
`403`	`missing_scope`	The key lacks a scope this endpoint needs. See `details.missing_scopes`.

invalid_api_key covers both malformed keys and keys that do not exist. The API does not tell them apart, so it never reveals which key prefixes are real.

See Errors for the full error format and retry guidance.

Get started

Core concepts

Advanced

Use cases

Cookbooks

Resources

Create a key

Get a key from a coding agent

Scopes

Revoke and rotate keys

Authentication errors

​Create a key

​Get a key from a coding agent

​Scopes

​Revoke and rotate keys

​Authentication errors

Create a key

Get a key from a coding agent

Scopes

Revoke and rotate keys

Authentication errors