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

# Authentication

> Use API keys to authenticate every request to Phaseo Gateway.

Use this reference when you need to send authenticated requests or decide how to store and rotate keys.

Phaseo Gateway uses bearer tokens. Every API request must include a valid key from your workspace.

***

## Key types

* **Gateway API keys** call model, provider, and generation endpoints available to your workspace.
* **Management API keys** call administration APIs. See [Management API Keys](./management-api-keys.mdx).
* **Rotated keys** can be created at any time, then swapped into your app before the old key is removed.

Keys follow the format `phaseo_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>

***

## Header format

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

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

Most HTTP clients let you set this once on the client. For example, with `fetch`:

```ts theme={null}
const response = await fetch("https://api.phaseo.ai/v1/chat/completions", {
	method: "POST",
	headers: {
		Authorization: `Bearer ${process.env.PHASEO_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 handling checklist

| 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.        |

***

## Common authentication errors

* **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.
* **429 Too Many Requests**: the key or workspace exceeded a limit. See [Rate limits](./rate-limits.mdx).
* **5xx errors**: retry with exponential backoff and contact [support](https://phaseo.app/help) if the issue persists.