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

# Authentication

> How your Toolken key and your provider key work together.

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

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

<Tip>If a key starts with `sk-`, it is a provider key. It never goes in `X-Toolken-Key`.</Tip>

## Two keys, two jobs

<CardGroup cols={2}>
  <Card title="Toolken key" icon="key">
    `tk_live_...`

    Sent in `X-Toolken-Key`.

    Authenticates you to Toolken. Create and revoke in the dashboard.
  </Card>

  <Card title="Provider key" icon="plug">
    `sk-...` / `sk-ant-...`

    Sent in `Authorization: Bearer` (OpenAI-compatible) or `x-api-key` (Anthropic).

    Your existing provider key. Forwarded untouched.
  </Card>
</CardGroup>

## Where each key goes

<CodeGroup>
  ```python Python theme={null}
  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
  )
  ```

  ```bash curl theme={null}
  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"}]}'
  ```
</CodeGroup>

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:

<Steps>
  <Step title="Create a new key">Go to the dashboard under API Keys and generate a new Toolken key.</Step>
  <Step title="Deploy it">Update your app or service to send the new key in `X-Toolken-Key`.</Step>
  <Step title="Revoke the old one">Delete the previous key from the dashboard. It stops working within about a minute.</Step>
</Steps>

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

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

## 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](/faq/troubleshooting) for the full list.

## What's next

<CardGroup cols={2}>
  <Card title="Observability" icon="chart-line" href="/features/observability/overview">See what the two keys buy you: cost, usage, and performance per agent, feature, and customer.</Card>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">Make your first request.</Card>
</CardGroup>