> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trygateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trygateway.ai/_mcp/server.

# Authentication

Every request to Gateway AI's proxy is authenticated with a **proxy key**. Proxy keys are created in your dashboard and scoped to your organization.

## Key format

Proxy keys look like this:

```
sk-proxy-a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
```

They always start with `sk-proxy-` followed by 64 hex characters.

## Sending your key

You can send your proxy key in any of three headers:

### Authorization header (recommended)

```
Authorization: Bearer sk-proxy-YOUR_KEY_HERE
```

This is the default for the OpenAI SDK and most HTTP clients.

### x-api-key header

```
x-api-key: sk-proxy-YOUR_KEY_HERE
```

This is the default for the Anthropic SDK.

### x-goog-api-key header

```
x-goog-api-key: sk-proxy-YOUR_KEY_HERE
```

This is the default for the Google Generative AI (Gemini) SDK.

All three work on every endpoint. The gateway detects `sk-proxy-` prefixed values in any of these headers.

## What happens to provider credentials

When the gateway receives your request:

1. Your `Authorization`, `x-api-key`, `x-goog-api-key`, and `Host` headers are **stripped**
2. Your proxy key is validated (active, not expired, IP allowed, etc.)
3. The real provider API key is **injected** into the correct header for the target provider
4. The request is forwarded to the provider

Your code never sees or handles the real provider API key. It stays on the server.

## Key validation

Every request is checked against these rules:

| Check                | What happens                                                     |
| -------------------- | ---------------------------------------------------------------- |
| **Key exists**       | 401 `invalid proxy key` if not found                             |
| **Key is active**    | 403 `key_revoked` if revoked                                     |
| **Key not expired**  | 403 `key_expired` if past expiry date                            |
| **IP allowed**       | 403 `ip_blocked` if client IP not in allowlist                   |
| **Provider allowed** | 403 `provider_not_allowed` if provider not in key's allowed list |
| **Model allowed**    | 403 `model_not_allowed` if model not in key's allowed list       |
| **Rate limit**       | 429 `rate_limited` if RPM exceeded                               |
| **Spend limit**      | 403 `spend_exceeded` if key spend limit reached                  |
| **Credit balance**   | 403 `insufficient_credits` if org has no credits                 |
| **Budget limit**     | 403 `budget_exceeded` if org budget config exceeded              |

## Dashboard vs. proxy authentication

Gateway AI has two auth systems:

* **Proxy keys** (`sk-proxy-...`) — for LLM proxy requests (`/openai/*`, `/anthropic/*`, `/gemini/*`, `/v1/chat/completions`)
* **Firebase JWT** — for the management API and dashboard (`/v1/account`, `/v1/keys`, `/v1/usage`, etc.)

Your developers use proxy keys. Your dashboard and management API use Firebase authentication.