API ReferenceByok

Create a BYOK provider credential

Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. Defaults to the authenticated entity’s default workspace; use the workspace_id body field to scope to a different workspace. Management key required.

Authentication

AuthorizationBearer
API key as bearer token in Authorization header

Request

This endpoint expects an object.
keystringRequired>=1 character
The raw provider API key or credential. This value is encrypted at rest and never returned in API responses.
providerenumRequired

The upstream provider this credential authenticates against, as a lowercase slug (e.g. openai, anthropic, amazon-bedrock).

allowed_modelslist of strings or nullOptional

Optional allowlist of model slugs this credential may be used for. null means no restriction.

allowed_user_idslist of strings or nullOptional

Optional allowlist of user IDs that may use this credential. null means no restriction.

disabledbooleanOptional
Whether this credential should be created in a disabled state.
is_fallbackbooleanOptional

Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried.

namestring or nullOptional<=255 characters

Optional human-readable name for the credential.

workspace_idstringOptionalformat: "uuid"
Optional workspace ID. Defaults to the authenticated entity's default workspace.

Response

BYOK credential created successfully
dataobject
The created BYOK credential.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error