Declare the tenant's own BYOK key-material backend

put

https://staging.ankatech.co/api/v3/admin/tenants/{tenantId}/key-backend/byok

Required scope: admin.tenant.key-backend.byok.declare.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

tenantId

uuid

required

Body Params

Declares a tenant's own (BYOK) key-material backend: non-secret connection config plus a structured, per-provider write-only access credential sealed under the tenant's Plane-2 KEK. The credential is never returned on a read.

backendType

string

enum

required

length ≥ 1

Key-material backend from the closed 9-value set of declarable backends (4 PKCS#11 HSM vendors + 5 Cloud KMS backends). Normalized to its lowercase slug for persistence (e.g. AWS-KMS -> aws-kms).

endpoint

string

length between 0 and 255

^https://[^\s]{3,}$

Non-secret backend connection endpoint (an absolute https URL to the KMS/HSM). Its requiredness is PER BACKEND, declared once beside the vocabulary and enforced server-side (422 when violated): REQUIRED for azure-kv and azure-kv-mhsm, where the endpoint IS the vault / Managed HSM URL and there is no backend to reach without it; OPTIONAL for aws-kms, where it pins egress and, when omitted, the SDK resolves its default regional endpoint; NOT ACCEPTED for gcp-kms and gcp-kms-hsm (their identity is the resource path already carried in keyId) and for softhsm, nshield, luna and cloudhsm (their identity is the token label and the vendor profile). Supplying one to a backend that does not accept it is REFUSED, not accepted and discarded. When supplied it is SSRF-validated server-side: loopback/private/link-local/cloud-metadata hosts are rejected.

keyId

string

required

length between 0 and 255

^[A-Za-z0-9:/._\-]+$

Non-secret backend-side KEK identifier that wraps this tenant's DEK (an ARN, cloud resource path, or HSM key label).

credential

required

Structured, per-provider write-only backend access credential (sealed under the tenant's Plane-2 KEK; never returned, logged, or audited). Its provider family must match the declared backend type.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Backend declared (pending bind).

400Invalid backend type/endpoint/keyId.

401Missing or invalid JWT.

403Wrong tenant, missing scope, or tenant not entitled.

404The tenant does not exist, or has been soft-deleted.

503The key-material-exists immutability probe (S2S to Core API) could not be answered, so the declare is DENIED fail-closed rather than applied on an unverified assumption. Retryable; carries Retry-After.