Bring Your Own Keys (BYOK)

By default, Mesh API routes inference through shared system credentials managed by us. With BYOK, you register your own provider API keys. Requests from your account then use your keys — giving you direct billing, quota control, negotiated rates, data-residency control, and access to provider-side features tied to your own account.

BYOK is opt-in and optional. Running on Mesh’s provider credentials is the right choice for most accounts.

Supported providers

Provider	Registration endpoint	Credential type
AWS Bedrock	`POST /v1/provider-keys/aws`	Bedrock API key (region-locked) or IAM access key + secret
Google Vertex AI	`POST /v1/provider-keys/vertex`	Service account JSON fields
OpenAI	`POST /v1/provider-keys/openai`	API key
Azure AI Foundry	`POST /v1/provider-keys/azure-foundry`	Project endpoint + API key
Anthropic, Arcee, Cerebras, Cohere, DeepSeek, Fireworks, Moonshot, Parasail, Perplexity, Qwen (DashScope), Sarvam	`POST /v1/provider-keys/{provider}`	API key

There is no separate Azure OpenAI registration. One Azure AI Services key serves both hostnames, so register it as Azure AI Foundry. The pasted-key list is served by GET /v1/provider-keys/supported, which the dashboard’s provider picker renders from. AWS Bedrock, Vertex AI, OpenAI, and Azure AI Foundry have a matching test endpoint. POST /v1/provider-keys/test/{provider} validates credentials without saving them, and POST /v1/provider-keys/test/{pk_id}/{provider} re-tests one you already registered ({provider} is aws, vertex, openai, or azure-foundry). A pasted key is validated against the provider when you save it: a rejected key returns 422 and nothing is stored. Credential checks are limited to 10 per minute per account.

Platform fee

BYOK traffic carries a platform fee of 5% of the request’s cost at Mesh’s list price. The first 1,000,000 BYOK tokens each month are fee-free. The fee counts toward your spend caps.

Adding a provider key

Via Dashboard

Open the Dashboard and select BYOK from the sidebar. The page lists each supported provider; select the one you want to configure. Inside the provider page, use the Add button to register a key. You can add multiple keys per provider, but only one can be active at a time. A new key is saved inactive, so enable the one you want to use. The /v1/provider-keys endpoints back this page. They take a signed-in dashboard session; an rsk_ or mak_ key gets 401. Registering, rotating, and removing provider keys is always a dashboard action. The bodies under Credential format by provider show what each form collects. Credentials are stored encrypted in GCP Secret Manager — plaintext is never written to the database.

Using a provider key

Once registered, requests for that provider automatically use your key based on the team associated with your API key. No changes to your API call are required — the routing is transparent.

Fallback behavior

By default, if your key fails due to an auth error or rate limit, the request transparently retries using the shared system credentials. To disable this, turn off Allow fallback on the key (allow_fallback: false):

{
  "credential_type": "iam_credentials",
  "access_key_id": "AKIA...",
  "secret_access_key": "...",
  "region": "us-east-1",
  "allow_fallback": false,
  "team_id": "your-team-uuid"
}

This is useful for compliance scenarios where requests must not leave your account. A response served by the fallback carries the X-BYOK-Fallback-Triggered header. Don’t confuse it with X-Mesh-Routing-Fallback, which is about providers and models rather than credentials — see Retry & Fallback. Both can appear on the same response.

Limit a key to specific models

By default a provider key serves every model Mesh routes to that provider. Allowed models narrows it to the models you name. Use it when the credential belongs to one contract, one budget, or an approved model set. Set it in the dashboard when you add or edit a key: BYOK → the provider → Allowed models. The list takes:

exact model IDs, such as openai/gpt-4.1-mini
brand wildcards, such as openai/*, which cover every model of that brand, including ones added later

The list holds up to 200 entries. Each entry is checked against the model catalog when you save: an unknown ID, or a brand with no enabled model, returns 422 and nothing is saved. An empty list means every model. In the request body the field is allowed_models, on every create and update endpoint under Key management:

{
  "api_key": "sk-...",
  "label": "Contract A",
  "allowed_models": ["openai/gpt-4.1-mini", "openai/gpt-4.1"],
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

On an update, leaving allowed_models out keeps the current list. null or [] clears it.

A model outside the list

Your key is never used for a model outside its list. What happens instead depends on Allow fallback:

Allow fallback	Result
On (default)	Mesh’s credentials serve the request as an ordinary request. It is billed to your Mesh balance at Mesh’s price, the BYOK platform fee does not apply, and a zero balance returns `402`. This is not a fallback: on chat completions, Responses and embeddings the response carries `X-BYOK-Used: false` and `X-BYOK-Fallback-Triggered: false`.
Off	`403` with `error.code` `byok_model_not_allowed`. Nothing is sent to the provider.

To serve an out-of-scope model on your own key, add the model or its brand wildcard to the list. A few things to know:

The list never grants access. Model policies on the API key, team, and organization are checked first, and a model they block is refused (403 model_excluded) whatever the key allows. Allowed models only decides whose credential serves a model that is already permitted.
It applies everywhere the key is used. That includes calls Mesh makes for you: the Auto Router’s request classification, and the underlying models of a composite model (is_composite in the model reference). With fallback off, a list that excludes one of a composite model’s underlying models refuses requests for the composite model.
Avoid changing the list while batch, video, or background jobs are running. A running job is checked with the credential the new list picks. If that is a different provider account from the one that accepted the job, the check fails.

Key management

Endpoints the dashboard calls, for reference:

Action	Endpoint
Add key (AWS)	`POST /v1/provider-keys/aws`
Add key (Vertex AI)	`POST /v1/provider-keys/vertex`
Add key (OpenAI)	`POST /v1/provider-keys/openai`
Add key (Azure AI Foundry)	`POST /v1/provider-keys/azure-foundry`
Add key (pasted-key providers)	`POST /v1/provider-keys/{provider}`
List pasted-key providers	`GET /v1/provider-keys/supported`
List keys	`GET /v1/provider-keys`
Key stats	`GET /v1/provider-keys/stats`
Get key	`GET /v1/provider-keys/{id}`
Enable / disable, relabel, change allowed models	`PATCH /v1/provider-keys/{id}`
Update / rotate credential	`PATCH /v1/provider-keys/{aws,vertex,openai,azure-foundry}/{id}`, or `PATCH /v1/provider-keys/generic/{id}` for a pasted key
Delete key	`DELETE /v1/provider-keys/{id}`
Validate credentials (no save)	`POST /v1/provider-keys/test/{provider}`
Test an existing key	`POST /v1/provider-keys/test/{id}/{provider}`

Deleting a provider key is a soft delete — the record is retained for billing history but excluded from future routing. Provider UUIDs are preserved for foreign key integrity.

Credential format by provider

AWS Bedrock — IAM credentials

{
  "credential_type": "iam_credentials",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key": "wJalrXUtnFEMI...",
  "region": "us-east-1",
  "label": "My Bedrock key",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

Ensure the IAM user or role has bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, and bedrock:ListFoundationModels permissions on the models you intend to use.

AWS Bedrock — Bedrock API key

{
  "credential_type": "bedrock_api_key",
  "api_key": "your-bedrock-api-key",
  "region": "us-east-1",
  "label": "My Bedrock API key",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

Bedrock API keys are region-locked — the region must match the AWS region where the key was created and cannot be changed after creation.

Google Vertex AI

Provide the service account key fields directly (as downloaded from the GCP console or gcloud iam service-accounts keys create):

{
  "type": "service_account",
  "project_id": "my-gcp-project",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
  "client_email": "my-sa@my-project.iam.gserviceaccount.com",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/...",
  "universe_domain": "googleapis.com",
  "region": "us-central1",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

The service account needs the roles/aiplatform.user role and aiplatform.endpoints.predict permission on your GCP project. Omit region or set it to "global" to allow requests to run in any available region.

OpenAI

{
  "api_key": "sk-...",
  "label": "My OpenAI key",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

Azure AI Foundry

{
  "api_key": "your-azure-ai-services-key",
  "endpoint": "https://my-resource.services.ai.azure.com/api/projects/my-project",
  "label": "My Foundry key",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

endpoint is the full project endpoint URL; either the primary or secondary key works.

Pasted-key providers

{
  "api_key": "your-provider-api-key",
  "label": "My Anthropic key",
  "allow_fallback": true,
  "team_id": "your-team-uuid"
}

The provider is the last path segment, for example POST /v1/provider-keys/anthropic.

Troubleshooting

Common BYOK failures and their causes:

Status	Cause
`401 Unauthorized`	Your provider API key is invalid, revoked, or malformed for that provider
`403 Forbidden`	The key lacks permission for the requested model — e.g. an AWS IAM policy missing `bedrock:InvokeModel`
`429 Too Many Requests`	You hit the rate limit on your own provider account

BYOK errors surface with the provider’s HTTP status, not Mesh’s. A 401 here means your provider key was rejected — not your rsk_ key.

For a symptom-by-symptom walkthrough, see Troubleshooting → BYOK.

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Bring Your Own Keys (BYOK)

Supported providers

Platform fee

Adding a provider key

Via Dashboard

Using a provider key

Fallback behavior

Limit a key to specific models

A model outside the list

Key management

Credential format by provider

Troubleshooting

​Supported providers

​Platform fee

​Adding a provider key

​Via Dashboard

​Using a provider key

​Fallback behavior

​Limit a key to specific models

​A model outside the list

​Key management

​Credential format by provider

​Troubleshooting

Supported providers

Platform fee

Adding a provider key

Via Dashboard

Using a provider key

Fallback behavior

Limit a key to specific models

A model outside the list

Key management

Credential format by provider

Troubleshooting