> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# Authentication

> API keys, request headers, server-side proxy, and key rotation

JoyToken uses API key authentication. Model calls should be sent from your server using the header for the selected compatible API.

## Common Request Headers

| Common header  | Required    | Description                             |
| -------------- | ----------- | --------------------------------------- |
| `Content-Type` | Yes         | `application/json`                      |
| `X-Request-ID` | Recommended | Log, billing, and debugging correlation |

> **Warning**
>
> Do not send both `Authorization` and `X-API-Key` on the same request. If both are present, the current gateway reads `X-API-Key` first.

## Choose a Protocol

#### OpenAI

Authentication header:

```text
Authorization: Bearer $JOY_TOKEN_API_KEY
```

The same header authenticates both `POST /openai/v1/responses` and `POST /openai/v1/chat/completions`.

Set `JOY_TOKEN_OPENAI_BASE_URL` from [Environments](/user-guide/environments) before running the example.

```bash
curl "$JOY_TOKEN_OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: auth-example-001" \
  -d '{
    "model": "auto",
    "input": "ping"
  }'
```

#### Anthropic

Authentication header:

```text
x-api-key: $JOY_TOKEN_API_KEY
```

Set `JOY_TOKEN_ANTHROPIC_BASE_URL` from [Environments](/user-guide/environments) before running the example.

```bash
curl "$JOY_TOKEN_ANTHROPIC_BASE_URL/messages" \
  -H "x-api-key: $JOY_TOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "ping" }],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

## Server-Side Proxy

Browsers and mobile apps should not hold JoyToken API keys. Recommended structure:

```text
Browser / App -> Your backend -> JoyToken
```

#### OpenAI

```ts
export async function POST(req: Request) {
  const body = await req.json();
  const baseUrl = process.env.JOY_TOKEN_OPENAI_BASE_URL;

  const response = await fetch(`${baseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.JOY_TOKEN_API_KEY}`,
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}
```

To proxy the Responses API instead, send the same authenticated request to `${baseUrl}/responses`. Keep the upstream path fixed in server code rather than accepting an arbitrary path from the browser.

#### Anthropic

```ts
export async function POST(req: Request) {
  const body = await req.json();
  const baseUrl = process.env.JOY_TOKEN_ANTHROPIC_BASE_URL;

  const response = await fetch(`${baseUrl}/messages`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.JOY_TOKEN_API_KEY ?? "",
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify(body),
  });

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}
```

## Checks After Authentication

| Check                         | Failure response            |
| ----------------------------- | --------------------------- |
| Key is valid and active       | `403 invalid_api_key`       |
| IP, tier, and model policy    | `403 policy_rejected`       |
| Wallet balance and key budget | `402 insufficient_quota`    |
| Request body validity         | `400 invalid_request_error` |

## Rotate an API Key

1. Create a new key with the same or stricter policy.
2. Write it to your server-side secret manager or environment variables.
3. Send one verification request with `X-Request-ID`.
4. Confirm logs and usage in JoyToken Console.
5. Disable or revoke the old key.

## Security Practices

| Practice                                  | Reason                                        |
| ----------------------------------------- | --------------------------------------------- |
| One key per app and environment           | Easier budgets, policy, and usage attribution |
| Set budgets and tier limits for test keys | Cost control                                  |
| Use separate keys for high-risk agents    | Avoid unattended overspend                    |
| Revoke leaked keys immediately            | Do not keep using exposed keys                |