Skip to main content

Keys and BYOK

API keys
Direct 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 typeScopeCreated from
Project keyOne project. Usage is attributed to the project, and responses include x-gateway-project.Gateway > API keys inside a project
Organization keyThe 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 key
Direct 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/models lists 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.

Rolling out

Per-key spend limits (daily, weekly, monthly, or lifetime, from $1) are rolling out and may not appear in your organization yet.

Rotate and revoke
Direct 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 keys
Direct link to Deployment keys

Rolling out

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

ProviderSupported endpoints
OpenAIChat Completions, Responses, Embeddings, Decisions
AnthropicMessages
GoogleChat Completions and Embeddings (OpenAI-compatible)
Custom HTTPS endpointChat 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:

  1. Open Gateway > BYOK in projects.mastra.ai.
  2. Add a connection with your provider API key.
  3. 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.

On this page