Keys and BYOK
API keysDirect link to API keys
Gateway keys start with msk-gateway-. Send a key in either header:
Authorization: Bearer msk-gateway-...
x-api-key: msk-gateway-...
| Key type | Scope | Created from |
|---|---|---|
| Project key | One project. Usage is attributed to the project, and responses include x-gateway-project. | Gateway > API keys inside a project |
| Organization key | The whole organization. | Gateway > API keys at organization level |
Keys are shown once when created. Gateway stores only a hash.
Keys that start with msk_ belong to the previous Memory Gateway and don't work with the current API. Memory Gateway shuts down on December 31, 2026. See Migrate.
Restrict a keyDirect link to Restrict a key
When you create a key, you can set:
- Label: A name to identify the key.
- Expiry: A date after which the key stops working.
- Allowed models: The only models the key can call.
/v1/modelslists only those models for the key. - Disable failover: Keep each request on a single route.
You can rename project and organization keys at any time. Expiry, allowed models, and failover are fixed at creation. To change them, create a new key and revoke the old one.
Per-key spend limits (daily, weekly, monthly, or lifetime, from $1) are rolling out and may not appear in your organization yet.
Rotate and revokeDirect link to Rotate and revoke
- Organization keys can be rotated. Rotation issues a new secret for the same key.
- Project keys are revoked and replaced. Create the new key, update your application, then revoke the old one.
Revoked and expired keys return 401.
Deployment keysDirect link to Deployment keys
Automatic deployment keys are rolling out by organization.
When enabled, Mastra platform injects a Gateway key into each deploy as MASTRA_GATEWAY_API_KEY, so deployed agents can call Gateway without manual setup. The key is scoped to the deploy and is revoked when the deploy stops, fails, or is cancelled. A key you set yourself isn't replaced.
Turn injection on or off, and restrict allowed models, in project settings. A deployment-key spend limit can be saved in project settings, but it isn't enforced on the key yet.
Bring your own keyDirect link to Bring your own key
A BYOK connection routes requests through your own provider account. The provider bills you directly, and Gateway doesn't charge Mastra credit for those requests.
| Provider | Supported endpoints |
|---|---|
| OpenAI | Chat Completions, Responses, Embeddings, Decisions |
| Anthropic | Messages |
| Chat Completions and Embeddings (OpenAI-compatible) | |
| Custom HTTPS endpoint | Chat Completions, Responses, and Messages |
Images, audio, and rerank aren't available over BYOK.
An Anthropic connection also serves /v1/messages/count_tokens and the Anthropic Files API through the same key.
To set up a connection:
- Open Gateway > BYOK in projects.mastra.ai.
- Add a connection with your provider API key.
- Optionally assign the connection to projects. Keys in those projects then use it for that provider.
Each connection's proxy key can have an expiry and a spend limit, set when you add the connection. You can edit the spend limit later, but not the expiry. Custom endpoint connections support an expiry only.
BYOK requests make one attempt on your connection and don't fail over to another provider. Allowed-model restrictions and organization policy still apply. If the connection is inactive, requests return 403 with byok_connection_inactive.