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

# Authenticate Your Tokonomics API Key on Every Request

> Tokonomics uses API keys for authentication. Every request must include your mk_ key in the Authorization header as a Bearer token.

Every request you send through the Tokonomics proxy must be authenticated with an API key. Tokonomics uses standard Bearer token authentication — you include your key in the `Authorization` header of each HTTP request, and the proxy validates it before forwarding anything upstream. There are no sessions, cookies, or OAuth flows to manage.

## Your API key

Tokonomics API keys follow a fixed format: the prefix `mk_` followed by exactly 48 lowercase hexadecimal characters.

```text theme={null}
mk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
```

You generate keys in your dashboard under **API Keys → Create key**. Each key can be given a descriptive label so you can identify which service or team is using it. Keys are active immediately after creation.

<Warning>
  Tokonomics stores only a SHA-256 hash of your API key — the plaintext value is shown exactly once, at the moment of creation. If you lose your key, you must revoke it and generate a new one. There is no "reveal key" option.
</Warning>

## Passing your key

Include your API key as a Bearer token in the `Authorization` header of every request:

```text theme={null}
Authorization: Bearer mk_your_key_here
```

#### curl

```bash theme={null}
curl https://tokonomics.ca/proxy/openai/chat/completions \
  -H "Authorization: Bearer mk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

#### Python (openai SDK)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="mk_your_key_here",
    base_url="https://tokonomics.ca/proxy/openai/",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)
```

The `openai` SDK automatically sends whatever value you pass as `api_key` in the `Authorization: Bearer` header, so no additional configuration is needed.

<Note>
  Never include your API key in client-side code, browser bundles, or public repositories. Treat it with the same care as a database password. Use environment variables or a secrets manager to inject the key at runtime.
</Note>

## Multiple keys

You can create as many API keys as your plan allows and assign each one to a different service, team, or environment. This lets you:

* **Isolate spend by service** — a key for your backend API, a separate key for your data pipeline, another for internal tooling
* **Attribute cost by team** — give each team their own key and filter dashboard spend by key
* **Rotate keys safely** — generate a replacement key, deploy it, then revoke the old one without any downtime

Free plan accounts support up to 3 API keys. Pro plan accounts have unlimited keys. You can revoke any key instantly from the **API Keys** section of your dashboard — revocation takes effect immediately and all subsequent requests using that key are rejected.

## Error responses

If authentication fails or a limit is exceeded, Tokonomics returns a standard error response. The table below lists the authentication-related status codes you may encounter:

| Status                  | Reason                                        | Response body                                                                    | Notes                                                                               |
| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `401 Unauthorized`      | API key is missing or invalid                 | `{"error": "Unauthorized", "message": "Invalid or missing API key"}`             | Check that the `Authorization` header is present and that the key begins with `mk_` |
| `429 Too Many Requests` | Rate limit hit, or monthly budget cap reached | `{"error": "Too Many Requests", "message": "Rate limit or budget cap exceeded"}` | Includes a `Retry-After` header indicating how many seconds to wait before retrying |

When you receive a `401`, verify that:

1. The `Authorization` header is formatted exactly as `Bearer mk_your_key_here` (note the space after `Bearer`)
2. The key has not been revoked in your dashboard
3. You are not accidentally sending a raw provider key (e.g., `sk-...`) instead of your Tokonomics `mk_` key

When you receive a `429`, check your dashboard to determine whether you've hit a rate limit or exhausted your monthly call quota. On the Free plan, you can upgrade to Pro to remove the call cap.