BYOK operational guide
Operational guide for Bring Your Own Key — provider credential lifecycle, encryption, and troubleshooting.
Bring Your Own Key (BYOK) lets each project store its own provider API keys. This guide covers the operational aspects: encryption, lifecycle, troubleshooting, and interaction with other credential sources.
Note: For a user-facing introduction to BYOK, see the BYOK feature guide.
Encryption at rest
Provider credentials stored via BYOK are encrypted at rest:
- Algorithm: AES-256-GCM.
- The
GATEWAY_ENCRYPTION_KEYenvironment variable must be configured on the Gateway server. - Each credential is encrypted individually; the plaintext key is never persisted or logged.
- Only the key prefix and suffix are stored in plain text for identification.
Credential lifecycle
Credentials stored via BYOK follow a three-state lifecycle:
| Status | Description | Routing behaviour |
|---|---|---|
active | The key is valid and will be used for provider routing | Credential is eligible |
revoked | The key has been revoked; cannot be re-activated | Credential is skipped |
test_failed | Key failed a connectivity test; remains active for routing | Credential remains eligible until explicitly revoked |
When multiple credentials exist for the same project and provider, the most recently created active credential is used.
Credential resolution order
When the Gateway processes a request with an associated projectId:
- BYOK credentials are checked first. If an
activecredential exists for the requested provider, it is used. - Server-level environment variables (
OPENAI_API_KEY,ANTHROPIC_API_KEY, etc.) are used as fallback when no BYOK credential is present. - Desktop credential store uses Electron
safeStoragefor the local runtime; this is independent of the Gateway credential system.
The Gateway does not merge BYOK and server-level keys for the same provider — it uses whichever is resolved first from the order above.
Interaction with Desktop credential store
Desktop users can store provider credentials through the Desktop settings UI. These credentials use the Desktop credential store abstraction (safeStorage-backed), which is independent of Gateway BYOK storage. Desktop credentials apply only to local model runtime operations, not to Gateway API calls.
Troubleshooting
| Symptom | Likely cause | Check |
|---|---|---|
Credential shows test_failed | The provided API key is invalid or the provider endpoint is unreachable | Verify the key in the provider's dashboard and test connectivity |
| BYOK credential not being used for a request | Request does not include a projectId, or no active credential exists for the provider | Confirm the credential status and that the request includes a project ID |
| "Credential not available" on Desktop | Electron safeStorage is unavailable (headless environment) | Use environment variables as an alternative; Desktop credential store is unavailable in headless/test environments |
GATEWAY_ENCRYPTION_KEY not configured | Encryption key is missing | Add the environment variable to the Gateway server configuration |