> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Keys (BYOK)

> Use your own upstream provider credentials instead of the shared system keys.

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.

<Info>
  BYOK is opt-in and optional. Running on Mesh's provider credentials is the right choice for most accounts.
</Info>

## 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](https://app.meshapi.ai) 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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/platform/retry-and-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}` |

<Warning>
  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.
</Warning>

## Credential format by provider

<AccordionGroup>
  <Accordion title="AWS Bedrock — IAM credentials">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="AWS Bedrock — Bedrock API key">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="Google Vertex AI">
    Provide the service account key fields directly (as downloaded from the GCP console or `gcloud iam service-accounts keys create`):

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="OpenAI">
    ```json theme={null}
    {
      "api_key": "sk-...",
      "label": "My OpenAI key",
      "allow_fallback": true,
      "team_id": "your-team-uuid"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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                                                     |

<Note>
  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.
</Note>

For a symptom-by-symptom walkthrough, see [Troubleshooting → BYOK](/debug/byok).