> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.meshapi.ai/llms.txt.
> For full documentation content, see https://developers.meshapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.meshapi.ai/_mcp/server.

# BYOK

> Learn how to use your existing AI provider keys with Mesh API.

# Bring Your Own Keys (BYOK)

Mesh API supports both using Mesh API credits (platform credentials) and the option to bring your own provider keys (BYOK).

Using provider keys enables direct control over rate limits and costs via your provider account (e.g., AWS Bedrock, Google Vertex AI).

## How it Works

When you configure a BYOK key, Mesh API securely stores the reference and uses it for requests routed through that provider on your behalf.

By default, requests will use your BYOK key. If your key fails (e.g., due to authentication errors or rate limits), the request will fall back to using Mesh API's platform credentials, unless you have disabled fallback for that key.

### Key Fallback

You can control the fallback behavior for each key:

* **Fallback Enabled (Default)**: If your key fails or hits a rate limit, Mesh API will attempt to fulfill the request using shared platform credentials.
* **Exclusive Use**: You can disable fallback to ensure that requests for that provider ONLY use your key. If your key fails, the request will fail.

## Platform Fee

The platform fee is currently **0%** for all BYOK requests. You can use your own keys without any additional cost for now.

## Supported Providers

BYOK is supported for the following providers. Here is what you need to configure each:

### OpenAI

For OpenAI, you only need to provide your **API key**.

### AWS Bedrock

You can configure Bedrock using one of two methods:

**Method 1: Bedrock API Keys**
Simply provide your Bedrock API key as a string. Note that these keys are tied to a specific AWS region.

**Method 2: AWS Credentials (JSON)**
Alternatively, you can provide a JSON object with your AWS IAM credentials and region:

```json
{
  "accessKeyId": "your-aws-access-key-id",
  "secretAccessKey": "your-aws-secret-access-key",
  "region": "your-aws-region"
}
```

Ensure your IAM user or role has permissions for `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`.

### Google Vertex AI

To use Vertex AI, you must provide your Google Cloud **service account key** in JSON format. The key should contain all standard fields, and you can optionally include a `"region"` field to specify the deployment region (defaults to `"global"` if omitted).

Example service account key with optional region:

```json
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
  "client_id": "your-client-id",
  "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/your-service-account@your-project.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com",
  "region": "global"
}
```

Ensure the service account has the **Vertex AI User** (`roles/aiplatform.user`) role or at least the `aiplatform.endpoints.predict` permission.

## Debugging BYOK Issues

If your BYOK requests fail, you can debug the issue by checking the response or viewing logs.
Common issues include:

* **401 Unauthorized**: Your provider API key is invalid or revoked.
* **403 Forbidden**: Your key lacks permissions for the requested model (e.g., AWS IAM policy missing `bedrock:InvokeModel`).
* **429 Too Many Requests**: You have hit the rate limit on your provider account.