Authentication

Create a key with phaseo keys create --name <name> --json in the Phaseo CLI or in the dashboard, store it on your server, and send it as a bearer token with Gateway requests. Agents should use the CLI; see Manage Phaseo from an agent.

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.
Trusted workloads (beta) let Vercel deployments and GitHub Actions jobs call the Gateway with a short-lived OIDC token instead of a stored key. See Trusted Workloads.

Rotate a key by updating your application to use its replacement before invalidating the old credential. See the key rotation endpoint. Keys follow the format phaseo_v1_sk_<kid>_<secret>. Treat them like passwords and avoid storing them in client-side code or public repositories.

You can call :free models without depositing credits. Paid models require available wallet balance.

Header format

Include the key in the Authorization header on every request:

Authorization: Bearer phaseo_v1_sk_<kid>_<secret>

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

const response = await fetch("https://api.phaseo.app/v1/chat/completions", {
	method: "POST",
	headers: {
		Authorization: `Bearer ${process.env.PHASEO_API_KEY}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		model: "openai/gpt-5-nano",
		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.
5xx errors: retry with exponential backoff and contact support if the issue persists.

Last modified on October 29, 2026

Overview

Models & Routing

Features

Integrations

Workspace & Access

Reliability & Operations

Platform & Research

Migration Guides

Community

Key types

Header format

Key handling checklist

Common authentication errors

​Key types

​Header format

​Key handling checklist

​Common authentication errors

Key types

Header format

Key handling checklist

Common authentication errors