Bring your own key (BYOK)
How to store and use provider API keys per project for the Gateway.
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
- Store a provider API key for your project through the Gateway API Keys
dashboard.
- 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.
- 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.
- Models from a BYOK-configured provider that would otherwise show as
missing-key (server-level key not set) become runnable.
Requirements
- The
GATEWAY_ENCRYPTION_KEYenvironment 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, ortest_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.