Skip to main content
POST
/
v1
/
workspaces
/
{workspace_id}
/
byok-keys
Create BYOK key
import requests

url = "https://api.auriko.ai/v1/workspaces/{workspace_id}/byok-keys"

payload = {
    "provider": "<string>",
    "api_key": "<string>",
    "name": "<string>",
    "is_default": True,
    "account_tier": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "provider": "<string>",
  "name": "<string>",
  "key_prefix": "<string>",
  "is_default": true,
  "disabled": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "account_tier": "<string>",
  "last_validated_at": "2023-11-07T05:31:56Z"
}
Auriko validates the submitted secret against the provider before activation. Requires byok:write scope. Supports Idempotency-Key. Audit event: byok_key.created.
The provider secret is write-only: accepted once here, encrypted at rest, and never returned by any endpoint. Idempotency-Key replays return the redacted metadata response only — never the secret.
To replace a secret, create a new key, set it as default, then delete the old one. Validation outcomes: invalid credentials are rejected with 400 and nothing is saved; transient provider validation failures return a retryable 502 and nothing is saved. A 409 during an in-flight create with the same Idempotency-Key means the original request is still running. Wait and retry.
account_tier accepts the values from List Provider Account Tiers. When omitted, Auriko auto-detects the tier or falls back to the provider’s conservative default.
Auriko derives the key’s data policy from provider + tier.
May return 202 with propagation_status: "pending" while the change takes effect. Propagation completes within about 5 minutes.
All parameters, request/response schemas, and examples are auto-generated from the OpenAPI specification.

Authorizations

​
Authorization
string
header
required

API key authentication. Keys start with ak_ prefix. Example: Authorization: Bearer ak_live_xxxxxxxxxxxx

Headers

​
Idempotency-Key
string

Idempotency key for safe retries

Maximum string length: 255
Pattern: ^[A-Za-z0-9_-]+$

Path Parameters

​
workspace_id
string<uuid>
required

Workspace identifier

Body

application/json
​
provider
string
required

Provider identifier from GET /v1/byok/providers

​
api_key
string
required
write-only

Provider secret. Accepted once at creation, encrypted at rest, and never returned by any endpoint.

Minimum string length: 10
​
name
string | null

Human-readable name (defaults to " Key")

Required string length: 1 - 100
​
is_default
boolean
default:true

Whether this key becomes the provider's routing default

​
account_tier
string | null

Provider account tier from the tiers endpoint. Omit to let Auriko auto-detect or use the provider's conservative default.

Response

Created

BYOK key metadata. Redacted — the provider secret is never returned.

​
id
string<uuid>
required

Unique identifier for the BYOK key

​
workspace_id
string<uuid>
required

Workspace this key belongs to

​
provider
string
required

Provider identifier

​
name
string
required

Human-readable name for the key

​
key_prefix
string
required

Masked display prefix of the submitted secret

​
is_default
boolean
required

Whether this key is the provider's default for routing

​
disabled
boolean
required

Disabled keys are excluded from routing; the secret stays encrypted at rest

​
validation_status
enum<string>
required

Coarse validation status (no provider diagnostics)

Available options:
valid,
pending,
invalid,
error
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
account_tier
string | null

Provider account tier used for rate-limit and data-policy routing

​
account_tier_source
enum<string> | null

How the tier was determined

Available options:
auto_detected,
user_specified,
fallback,
null
​
last_validated_at
string<date-time> | null

When the key last passed validation (null if never)

​
propagation_status
enum<string> | null

"pending" while a routing-affecting change for this key's provider is committed but edge propagation has not yet been applied

Available options:
pending,
null