api-keys

POST `/v1/api-keys`

Create an API key.

Pengesahan

Hantar kunci API sebagai token pembawa. Kunci tersebut mesti membawa kebenaran apikeys.manage; kunci yang tidak mempunyainya akan ditolak dengan 403, bukan 404.

Tempat ID organisasi anda diletakkan

Titik akhir ini mengambil org_id sebagai medan dalam kandungan JSON.

ID organisasi anda terletak pada skrin kekunci API dalam papan pemuka anda, di sebelah kekunci itu sendiri. Ia adalah ID yang sama dalam setiap panggilan yang anda buat.

Cuba

Gantikan apa sahaja di dalam kurungan sudut dengan nilai anda sendiri, dan pemegang tempat kunci dengan kunci dari papan pemuka anda.

curl -X POST https://api.zinndigital.com/v1/api-keys \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": <string> }'

Sudah log masuk? Konsol API dalam papan pemuka anda mengisi id organisasi sebenar dan kunci anda sendiri, serta menjalankan permintaan terhadap API langsung supaya anda boleh melihat respons sebenar. Buka penamat ini dalam konsol API

Butiran

Mints a new per-org API key and returns the full `zdk_…` token **once** — only its hash is stored, so a lost token is replaced, never recovered. The requested `scopes` must be permissions the caller already holds in the target org; asking for one you do not hold is a `403` (a key can never out-scope its creator). Send an `Idempotency-Key` so a retry after a lost response returns the same token rather than orphaning a key. Requires `apikeys.manage`.

Parameter

Nama	Jenis	Diperlukan	Apakah ia
`Idempotency-Key (header)`	`string`	Tidak	Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats.

Badan permintaan

Nama	Jenis	Diperlukan	Apakah ia
`name`	`string`	Ya	—
`scopes`	`string[]`	Tidak	RBAC permission keys to grant. Each must be a permission the caller holds in the target org (a key can never out-scope its creator); an unheld scope is a `403`, an unknown one a…
`sandbox`	`boolean`	Tidak	Mint a sandbox (test-mode) key. Defaults to false.
`org_id`	`Uuid \| null`	Tidak	The organization the key belongs to. Defaults to the caller's org; the caller must hold `apikeys.manage` in the target org.

Respons

Nama	Jenis	Diperlukan	Apakah ia
`id`	`Uuid`	Ya	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`name`	`string`	Ya	—
`prefix`	`string`	Ya	The key's public lookup id (the middle segment of the token).
`scopes`	`string[]`	Ya	The RBAC permission keys this key may exercise.
`sandbox`	`boolean`	Ya	A sandbox (test-mode) key suppresses billing + provisioning (docs/09 §2).
`last_used_at`	`object`	Tidak	When the key last authenticated a request; null if never used.
`revoked_at`	`object`	Tidak	Always null on a listed/fetched key — revoked keys are not returned.
`created_at`	`string`	Ya	—
`token`	`string`	Ya	The full `zdk_<mode>_<prefix>_<secret>` token. Shown once, here only — store it now; it cannot be retrieved again, only replaced.

Ralat yang boleh dikembalikan oleh titik akhir ini

401 · 403 · 409 · 422 · 429