Key — API reference

Key

API keys: test_ and live_.

Keys let a program or a bank integration call the API without the operator token. A test key may only touch simulated programs and the sandbox; a live key only Column-sourced programs (403 either way). The secret is shown once at creation and only its sha256 is stored. For a key, the operator on the record is key:<prefix> unless an X-Operator header names a person.

ApiKey

Only the sha256 of the secret is stored; the secret is shown once at creation.

Field	Type	Notes
id	string (uuid)
name	string
mode	"test" \| "live"	test_ keys may only touch simulated programs and the sandbox; live_ keys touch Column programs.
prefix	string	First 12 characters of the secret, for display.
programId	string \| null (uuid)	null = every program on the tenant.
scopes	string[]	[] = all scopes the mode allows.
lastUsedAt	string \| null (date-time)
revokedAt	string \| null (date-time)
createdAt	string (date-time)

Endpoints

post/api/keys

Create an API key

live keys may be created only when the tenant's Column environment is live or the operator passes confirmLive: true. The secret (test_/live_ + 32 base64url characters) is returned exactly once.

Auth	Bearer + X-Operator
Operation	Key · POST /api/keys

Parameters

Name	In	Type	Notes
tenant (optional)	query	string	Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit.
Idempotency-Key (optional)	header	string	1–255 characters. A replay with the same body returns the stored status and body with `Idempotent-Replayed: true`; a different body under the same key is 409.

Request body (application/json, required) · object

Field	Type	Notes
name	string
mode	"test" \| "live"
programId (optional)	string (uuid) \| null
scopes (optional)	string[]
confirmLive (optional)	boolean

Responses

201 — The key with its secret, shown once. object

Field	Type	Notes
id	string (uuid)
name	string
mode	"test" \| "live"
prefix	string
secret	string

400 — Validation failed. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

401 — Bearer token missing or unknown. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

Example

curl -s -X POST "https://skoor.ai/risk/api/keys?tenant=demo" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Operator: you@bank.example" \
  -H "Content-Type: application/json" \
  -d '{"name":"Northwind integration","mode":"test","programId":null}'

get/api/keys

List keys (never the secret)

Auth	Bearer + X-Operator
Operation	Key · GET /api/keys

Parameters

Name	In	Type	Notes
tenant (optional)	query	string	Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit.

Responses

200 — Every key on the tenant, including revoked ones. Array of ApiKey

Field	Type	Notes
id	string (uuid)
name	string
mode	"test" \| "live"	test_ keys may only touch simulated programs and the sandbox; live_ keys touch Column programs.
prefix	string	First 12 characters of the secret, for display.
programId	string \| null (uuid)	null = every program on the tenant.
scopes	string[]	[] = all scopes the mode allows.
lastUsedAt	string \| null (date-time)
revokedAt	string \| null (date-time)
createdAt	string (date-time)

401 — Bearer token missing or unknown. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

Example

curl -s "https://skoor.ai/risk/api/keys?tenant=demo" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Operator: you@bank.example"

delete/api/keys/{id}

Revoke a key

Auth	Bearer + X-Operator
Operation	Key · DELETE /api/keys/{id}

Parameters

Name	In	Type	Notes
id	path	string (uuid)	Key id.
tenant (optional)	query	string	Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit.

Responses

200 — Revoked; the key stops working at once. ApiKey

Field	Type	Notes
id	string (uuid)
name	string
mode	"test" \| "live"	test_ keys may only touch simulated programs and the sandbox; live_ keys touch Column programs.
prefix	string	First 12 characters of the secret, for display.
programId	string \| null (uuid)	null = every program on the tenant.
scopes	string[]	[] = all scopes the mode allows.
lastUsedAt	string \| null (date-time)
revokedAt	string \| null (date-time)
createdAt	string (date-time)

401 — Bearer token missing or unknown. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

404 — Not this tenant's key. Error

Field	Type	Notes
error	string	What went wrong, in one sentence.
requestId (optional)	string	Present once the gateway is live: the X-Request-Id of the failed request.

Example

curl -s -X DELETE "https://skoor.ai/risk/api/keys/5f3c1c8e-2a44-4c0b-9d0f-2b0a2f6e7c11?tenant=demo" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Operator: you@bank.example"

← All objects