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 OpenAI	`POST /v1/provider-keys/azure`	Endpoint + API key
Azure AI Foundry	`POST /v1/provider-keys/azure-foundry`	Endpoint + API key

Every provider has 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. Validate before you rely on a key.

Platform fee

BYOK traffic carries a platform fee of 5% of upstream cost. The first 1,000,000 tokens each month are fee-free.

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 — enable the one you want to use.

Via API

Use the provider-specific registration endpoints. For example, to add an AWS Bedrock key using IAM credentials:

curl https://api.meshapi.ai/v1/provider-keys/aws \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_type": "iam_credentials",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "label": "My Bedrock key",
    "team_id": "your-team-uuid"
  }'

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, set allow_fallback: false when registering the key:

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

Key management

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 OpenAI)	`POST /v1/provider-keys/azure`
Add key (Azure AI Foundry)	`POST /v1/provider-keys/azure-foundry`
List keys	`GET /v1/provider-keys`
Key stats	`GET /v1/provider-keys/stats`
Get key	`GET /v1/provider-keys/{id}`
Update / rotate key	`PATCH /v1/provider-keys/{id}`
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"
}

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 CLI

Platform

Reference

Bring Your Own Keys (BYOK)

Supported providers

Platform fee

Adding a provider key

Via Dashboard

Via API

Using a provider key

Fallback behavior

Key management

Credential format by provider

Troubleshooting

​Supported providers

​Platform fee

​Adding a provider key

​Via Dashboard

​Via API

​Using a provider key

​Fallback behavior

​Key management

​Credential format by provider

​Troubleshooting

Supported providers

Platform fee

Adding a provider key

Via Dashboard

Via API

Using a provider key

Fallback behavior

Key management

Credential format by provider

Troubleshooting