Authentication

Two keys travel with every request, and they are not interchangeable.

Your provider key is forwarded to the provider verbatim and never stored. Toolken keeps only a one-way hash of your Toolken key.

If a key starts with sk-, it is a provider key. It never goes in X-Toolken-Key.

Two keys, two jobs

Toolken key

tk_live_...Sent in X-Toolken-Key.Authenticates you to Toolken. Create and revoke in the dashboard.

Provider key

sk-... / sk-ant-...Sent in Authorization: Bearer (OpenAI-compatible) or x-api-key (Anthropic).Your existing provider key. Forwarded untouched.

Where each key goes

client = OpenAI(
    base_url="https://gateway.toolken.ai/v1",
    api_key="sk-...",                                  # your provider key, forwarded untouched
    default_headers={"X-Toolken-Key": "tk_live_..."},  # your Toolken key
)

curl https://gateway.toolken.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Toolken-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

Toolken reads and strips its own X-Toolken-* headers before forwarding. Everything else, including your provider auth, passes through unchanged.

Managing keys

A key’s full value is shown once at creation. Store it securely.
Toolken keeps only a one-way hash. The raw value is never stored.
Revoking a key takes effect within about a minute.

Rotate without downtime using these steps:

Create a new key

Go to the dashboard under API Keys and generate a new Toolken key.

Deploy it

Update your app or service to send the new key in X-Toolken-Key.

Revoke the old one

Delete the previous key from the dashboard. It stops working within about a minute.

Use a separate key per environment or service so you can attribute and revoke them independently.

Signing in to the dashboard is separate from your Toolken API key. The API key is only for routing traffic through the gateway.

When authentication fails

Code	What it means and how to fix
`missing_api_key`	No `X-Toolken-Key` sent. Add your `tk_live_...` key.
`invalid_api_key`	Key unknown or revoked. Make sure you send `tk_live_...`, not `sk-...`.
`tenant_suspended`	Your workspace is not active.
`tenant_unavailable`	Your workspace cannot be verified right now. Retry shortly.
`auth_unavailable`	Auth is briefly down. Requests fail closed. Retry shortly.

See Troubleshooting for the full list.

What’s next

Observability

See what the two keys buy you: cost, usage, and performance per agent, feature, and customer.

Quickstart

Make your first request.

Getting Started

Observability

Providers & Routing

Rate Limits

Integrations

Use cases

Two keys, two jobs

Toolken key

Provider key

Where each key goes

Managing keys

When authentication fails

What’s next

Observability

Quickstart

​Two keys, two jobs

Toolken key

Provider key

​Where each key goes

​Managing keys

​When authentication fails

​What’s next

Observability

Quickstart

Two keys, two jobs

Where each key goes

Managing keys

When authentication fails

What’s next