# Authentication

> Authenticate ScaleMax API-credit and token keys securely, use the correct endpoint, and understand key scope, bearer headers, and credential errors.

ScaleMax uses bearer-token authentication. Every request includes an `Authorization` header with your API key.

## Getting a key

Use the ScaleMax API key provided to you, or choose API credit or a provider-scoped token pack (Claude, OpenAI, Gemini, Grok, Qwen, Local Models, or an exact-model pack such as DeepSeek V4 Flash) on the ScaleMax pricing page. First-time buyers receive a fresh API key after payment confirmation. ScaleMax is prepaid access, not a subscription SaaS.

## Sending the key

Include the key in the `Authorization` header of every request:

request:

```http
Authorization: Bearer YOUR_SCALEMAX_API_KEY
```

The header name and format are identical to OpenAI's. OpenAI-compatible SDKs use it unchanged with the matching `/v1` base URL; native Anthropic clients use the same Bearer key with their origin-only gateway URL.

## Key type and base URL

Do not infer the URL from the key name. Select the billing surface and client protocol below, then use only models returned by that key's authenticated catalog.

**Start with the key you bought.** Choose its billing path, then the row that matches your client's protocol.

| Key type | Protocol | Use with | Base URL |
| --- | --- | --- | --- |
| API Credit | OpenAI-compatible Chat Completions or Responses | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/v1` |
| API Credit | Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro` |
| Token Budget | OpenAI, Gemini, Grok, Qwen, DeepSeek, or Local Models token pack · OpenAI-compatible API | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` |
| Token Budget | Claude token pack · Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro/token` |
| Token Budget | Claude token pack · OpenAI-compatible adapter | OpenCode, Cursor, Roo Code, compatible SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` |

**The protocol decides whether the client field ends in `/v1`.** OpenAI-compatible clients use a base URL ending in `/v1`. Native Anthropic clients use the origin only, without `/v1`, because they append `/v1/messages` themselves. A Claude token key therefore reaches `/token/v1/messages` when the native client builds its request.

Use the key's matching billing surface and only models returned by its authenticated catalog. A Claude token key and an OpenAI token key are provider-scoped; neither can be swapped onto the other's models.

Claude Desktop is a native Anthropic client with its own third-party inference settings. Follow the [Claude Desktop guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop); it does not read Claude Code's configuration.

## Key properties

- **Active / inactive.** Revoked keys are rejected with a `401`.
- **Expiry date.** Hard expiry. After expiry the key returns `403`.
- **Per-key budgets.** Token-budget keys hold a prepaid token allowance; credit keys hold a USD balance. An exhausted balance returns `402` `insufficient_credit` — not `429`. Authentication itself still succeeds, so read-only endpoints such as model discovery keep working.
- **Per-key rate limits.** Configurable requests-per-minute. Returns `429`.
- **Per-key provider scope.** Keys can be OpenAI-compatible only, Claude-compatible only, both, or a named family such as Gemini, Grok, Qwen, Local Models, or an exact-model pack. Requests for a model outside the key scope return `403` [`model_not_in_plan`](https://docs.scalemax.pro/docs/error-codes#model_not_in_plan), which lists the models the key can use.

## Security

- Treat your key like a password. Don't commit it.
- Use environment variables (`SCALEMAX_API_KEY`) — never inline it in client-side code.
- If a key is lost or leaks, sign in to the customer dashboard and use **Replace lost key**. The remaining entitlement moves to the replacement and the old secret stops working immediately. Contact support only if you cannot access the self-service flow.

Next: [Quick Start](https://docs.scalemax.pro/docs/quick-start) — your first request in under a minute.