BYOK Credentials

Manage Bring Your Own Key (BYOK) credentials for AI provider access.

POST /v1/admin/byok/providers/:provider/credentials

Upload or rotate a BYOK credential.

Property	Value
Auth	`tenant_admin` role
Providers	`gemini`
Idempotent	Yes

Request


{
  "credential": "API key string",
  "mode": "create | rotate",
  "label": "optional description (1–120 chars)"
}

Field	Type	Required	Description
`credential`	string	Yes	The API key
`mode`	string	Yes	`create` for first-time setup, `rotate` to replace
`label`	string	No	Human-readable description (1-120 chars)

Behavior

Credentials are stored in Google Cloud Secret Manager
create mode is for first-time setup
rotate mode replaces the existing credential
Triggers onboarding state transition to validation_pending
Audit event: byok_credential_create or byok_credential_rotate

POST /v1/admin/byok/providers/:provider/credentials/validate

Validate a stored BYOK credential by making a test call to the provider.

Property	Value
Auth	`tenant_admin` role
Idempotent	Yes

Validation Process

Retrieves stored credential from Secret Manager
Makes test API call to Gemini (15s timeout)
Checks for auth errors (401), quota errors (429), network errors
Stores validation result with timestamp and error details
Updates onboarding state accordingly

Response


{
  "tenant_id": "string",
  "provider": "gemini",
  "validation_status": "passed | failed",
  "onboarding_state": "certification_pending | validation_pending",
  "checked_at": "ISO8601",
  "error": { "code": "string", "message": "string" }
}

Secret Resolution Modes

Mode	Config	Behavior
`env`	`PROVIDER_SECRET_RESOLUTION_MODE=env`	API key from `GEMINI_API_KEY_SECRET` env var
`db`	`PROVIDER_SECRET_RESOLUTION_MODE=db`	Per-tenant key from Secret Manager via `TenantProviderConfig.secretRef`