api-keys

POST `/v1/api-keys`

Create an API key.

احراز هویت

یک کلید API را به عنوان یک توکن حامل ارسال کنید. این کلید باید دارای مجوز apikeys.manage باشد؛ کلیدی که فاقد آن باشد با خطای 403 رد می‌شود، نه 404.

جایی که شناسه سازمان شما قرار می‌گیرد

این نقطه پایانی org_id را به عنوان یک فیلد در بدنه JSON دریافت می‌کند.

شناسه سازمان شما در صفحه کلیدهای API در داشبوردتان، در کنار خود کلید قرار دارد. این شناسه در تمام درخواست‌هایی که ارسال می‌کنید یکسان است.

امتحان کنید

هر چیزی را که داخل براکت‌های زاویه‌دار قرار دارد با مقادیر خودتان جایگزین کنید، و نگهدارنده کلید را با کلیدی از داشبورد خود جایگزین نمایید.

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

وارد شده‌اید؟ کنسول API در داشبورد شما شناسه سازمان واقعی و کلید خودتان را پر می‌کند و درخواست را روی API زنده اجرا می‌کند تا بتوانید پاسخ واقعی را ببینید. این نقطه پایانی را در کنسول API باز کنید

جزئیات

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

پارامترها

نام	نوع	الزامی	چیست
`Idempotency-Key (header)`	`string`	خیر	Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats.

بدنه درخواست

نام	نوع	الزامی	چیست
`name`	`string`	بله	—
`scopes`	`string[]`	خیر	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`	خیر	Mint a sandbox (test-mode) key. Defaults to false.
`org_id`	`Uuid \| null`	خیر	The organization the key belongs to. Defaults to the caller's org; the caller must hold `apikeys.manage` in the target org.

پاسخ

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

خطاهایی که این نقطه پایانی می‌تواند برگرداند

401 · 403 · 409 · 422 · 429