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

# Authentication

> Use API keys to authenticate every request to AI Stats Gateway.

The Gateway uses bearer tokens for authentication. Every request must include a valid API key issued from your workspace. Keys scope access to specific features, letting you separate environments or team responsibilities.

***

## API keys

* **API Keys** are scoped to all models and providers available to your organization.
* **Management API keys** are elevated credentials created in the dashboard and used for administration APIs. See the [Management API Keys](./management-api-keys.mdx) guide for details.
* **Rotation** is manual today, but you can create a new key at any time without downtime.

Keys follow the format `aistats_v1_sk_<kid>_<secret>`. Treat them like passwords and avoid storing them in client-side code or public repositories.

<Note>
  You can call `:free` models without depositing credits. Paid models require available wallet balance.
</Note>

***

## Request headers

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

```http theme={null}
Authorization: Bearer aistats_v1_sk_<kid>_<secret>
```

Most HTTP clients expose a dedicated configuration property. For example, with `fetch`:

```ts theme={null}
const response = await fetch("https://api.phaseo.app/v1/chat/completions", {
	method: "POST",
	headers: {
		Authorization: `Bearer ${process.env.AI_STATS_API_KEY}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		model: "gpt-5-nano-2025-08-07",
		messages: [
			{ role: "system", content: "You are a helpful assistant." },
			{
				role: "user",
				content: "Summarize the drawbacks to AI.",
			},
		],
	}),
});
```

***

## Key management

| Practice            | Why it matters                                                           |
| ------------------- | ------------------------------------------------------------------------ |
| Use one key per app | Makes it easy to rotate without affecting other services.                |
| Store keys securely | Secrets managers prevent accidental exposure in logs or error tracking.  |
| Monitor usage       | The dashboard shows per-key metrics so you can detect anomalies quickly. |
| Remove unused keys  | Deleting stale keys reduces the surface area for potential abuse.        |

***

## Troubleshooting

* **401 Unauthorized** -- The key is missing, invalid, or belongs to a disabled workspace.
* **403 Forbidden** -- The key exists but cannot access the requested provider or model. Check your plan or contact support.
* **429 Too Many Requests** -- You exceeded a rate limit. See the [Rate limits](./rate-limits.mdx) guide.
* **5xx errors** -- Retry with exponential backoff and report persistent issues via the support channel.