Onboard / Configure KMS

POST /admin/tenant-kms

Onboard a customer KMS provider. KnoxCall performs a live wrap + unwrap round-trip on a 32-byte test payload before committing — if the IAM/RBAC grant isn’t working, the request fails immediately and nothing is stored. Calling this endpoint when a KMS configuration already exists replaces it (UPSERT). The probe runs first; if it fails, the existing config is unchanged. Auth: Session JWT (Authorization: Bearer <session-token>) plus the X-Tenant-ID header, and the caller must have the owner or admin role. Requests missing X-Tenant-ID are rejected with 400 X-Tenant-ID header required. No step-up required.

Request body

provider — aws | gcp | azure kms_key_ref — The provider-specific key identifier:

AWS: full key ARN (arn:aws:kms:REGION:ACCOUNT:key/KEY-ID or .../alias/ALIAS)
GCP: full resource path (projects/P/locations/L/keyRings/R/cryptoKeys/K)
Azure: vault key URL (https://VAULT.vault.azure.net/keys/KEY-NAME)

config — Provider-specific authentication references. Static long-lived credentials (access keys, service account JSON, client secrets) are rejected at the API level.

Provider	Required	Optional
`aws`	`region`, `role_arn`	`external_id`
`gcp`	`impersonate_service_account`	`project_id`
`azure`	`vault_url`	`azure_tenant_id`, `client_id`, `client_secret_env_var`

curl -X POST https://admin.knoxcall.com/admin/tenant-kms \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "kms_key_ref": "arn:aws:kms:us-east-1:111122223333:key/abcd-1234",
    "config": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::111122223333:role/KnoxCallKMSAccess",
      "external_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

curl -X POST https://admin.knoxcall.com/admin/tenant-kms \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gcp",
    "kms_key_ref": "projects/my-project/locations/global/keyRings/knoxcall-keys/cryptoKeys/tenant-master-key",
    "config": {
      "impersonate_service_account": "knoxcall-kms-sa@my-project.iam.gserviceaccount.com",
      "project_id": "my-project"
    }
  }'

curl -X POST https://admin.knoxcall.com/admin/tenant-kms \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "azure",
    "kms_key_ref": "https://my-kv.vault.azure.net/keys/tenant-master-key",
    "config": {
      "vault_url": "https://my-kv.vault.azure.net",
      "azure_tenant_id": "aaaabbbb-cccc-dddd-eeee-ffffgggghhhh",
      "client_id": "11112222-3333-4444-5555-666677778888",
      "client_secret_env_var": "AZURE_KC_CLIENT_SECRET"
    }
  }'

Response

{
  "ok": true,
  "provider": "aws",
  "kms_key_ref": "arn:aws:kms:us-east-1:111122223333:key/abcd-1234",
  "new_key_version": 1,
  "new_key_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "rewrap_status": "enqueued",
  "note": "A background rewrap pass will re-encrypt existing tenant data under the new key. Existing in-flight agent sessions remain valid for up to 5 minutes (BYOK session TTL)."
}

rewrap_status is always "enqueued" — KnoxCall unconditionally issues a background rewrap lease after onboarding.

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

POST /admin/tenant-kms

Request body

Response

​POST /admin/tenant-kms

​Request body

​Response

POST /admin/tenant-kms

Request body

Response