# Bring your own key (BYOK)

BYOK lets each project store its own provider API keys. When a project has a
stored key for a provider, the Gateway uses that key instead of, or in addition
to, the server-level environment variable for that provider.

## How it works

1. **Store** a provider API key for your project through the Gateway API Keys
   dashboard.
2. The key is **encrypted at rest** using AES-256-GCM and stored in the
   `gateway_provider_credentials` table. Only the key prefix and suffix are
   stored in plain text for identification.
3. When the Gateway processes a request, it looks up the project's stored key
   for the selected provider. If found, the key is decrypted and used for the
   upstream provider call. The plaintext key is never persisted or logged.
4. Models from a BYOK-configured provider that would otherwise show as
   `missing-key` (server-level key not set) become runnable.

## Requirements

- The `GATEWAY_ENCRYPTION_KEY` environment variable must be configured on the
  Gateway server.
- Supabase storage must be available for credential persistence.
- You must be a project owner or admin to create or revoke credentials.

## Key lifecycle

Credentials stored via BYOK have a status lifecycle:

| Status | Description |
|---|---|
| `active` | The key is valid and will be used for provider routing. |
| `revoked` | The key has been revoked and will not be used. Revoked keys cannot be re-activated. |
| `test_failed` | The key failed a connectivity test. It remains active for routing until explicitly revoked. |

## Provider scope

Each credential is scoped to a single project and provider ID. If multiple
credentials exist for the same project and provider, the most recently created
active credential is used.

Credential metadata returned by the Gateway dashboard includes:

- Provider ID and label
- Key prefix (first 8 characters) and suffix (last 4 characters)
- Status (`active`, `revoked`, or `test_failed`)
- Creation and last-tested timestamps
- Creator user ID

The raw key is never returned after creation.

## Interaction with server-level keys

BYOK and server-level environment variables (`OPENAI_API_KEY`,
`ANTHROPIC_API_KEY`, etc.) are independent. The Gateway checks BYOK first when
the request includes a project ID. When a BYOK key is available, the Gateway
uses it regardless of whether the server-level key is also set.

## See also

- [Providers, routing, and fallbacks](/docs/gateway/providers)
- [Authentication and API keys](/docs/gateway/authentication)
- [Gateway overview](/docs/gateway/overview)