api-keys

POST `/v1/api-keys`

Create an API key.

Kimlik Doğrulama

Bearer token olarak bir API anahtarı gönderin. Anahtar apikeys.manage iznine sahip olmalıdır; bu izne sahip olmayan bir anahtar 404 ile değil, 403 ile reddedilir.

Kurum kimliğinizin yazılacağı yer

Bu uç nokta, JSON gövdesinde bir alan olarak org_id alır.

Kuruluş kimliğiniz (id), kontrol panelinizdeki API anahtarları ekranında, anahtarın hemen yanında yer alır. Yaptığınız her çağrıda aynı kimlik kullanılır.

Dene

Köşeli parantez içindeki her şeyi kendi değerlerinizle ve anahtar yer tutucusunu panonuzdan bir anahtarla değiştirin.

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

Oturum açtınız mı? Panonuzdaki API konsolu, gerçek organizasyon kimliğinizi ve kendi anahtarınızı otomatik olarak doldurur ve isteği canlı API üzerinde çalıştırarak gerçek yanıtı görmenizi sağlar. Bu uç noktayı API konsolunda açın

Ayrıntılar

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`.

Parametreler

Ad	Tür	Zorunlu	Ne olduğu
`Idempotency-Key (header)`	`string`	Hayır	Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats.

İstek gövdesi

Ad	Tür	Zorunlu	Ne olduğu
`name`	`string`	Evet	—
`scopes`	`string[]`	Hayır	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`	Hayır	Mint a sandbox (test-mode) key. Defaults to false.
`org_id`	`Uuid \| null`	Hayır	The organization the key belongs to. Defaults to the caller's org; the caller must hold `apikeys.manage` in the target org.

Yanıt

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

Bu uç noktanın dönderebileceği hatalar

401 · 403 · 409 · 422 · 429