# BYOK operational guide

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](/docs/gateway/byok).

## Encryption at rest

Provider credentials stored via BYOK are **encrypted at rest**:

- Algorithm: AES-256-GCM.
- The `GATEWAY_ENCRYPTION_KEY` environment 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`:

1. **BYOK credentials** are checked first. If an `active` credential exists for the requested provider, it is used.
2. **Server-level environment variables** (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) are used as fallback when no BYOK credential is present.
3. **Desktop credential store** uses Electron `safeStorage` for 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 |

## See also

- [BYOK feature guide](/docs/gateway/byok)
- [Credential management](/docs/security/credential-management)
- [Security overview](/docs/security/overview)
- [Gateway overview](/docs/gateway/overview)