Platitun · API · Access keys · Issue a key

Issue a key

POST /api/v1/keys

Key scope: keys · changes data, the Idempotency-Key header is required

A new access key. It is shown ONCE — there is no second showing because we do not know it: only a hash is stored.

🔴 A key cannot grant scopes it does not hold itself. Otherwise one leaked key with the “keys” scope would become full account access, including the payout account, and revoking would not help: it had already issued itself a second one. A key with any scopes is issued from the cabinet by a human.

Request fields

Field	Type	What it is
`name` required	`string`	A name for yourself: “upload bot”, “stats collector”. Without names, in six months your key list is a list of identical strings.
`scopes` required	`array`	Scopes. Tick only what is needed: a leaked key can do exactly what is ticked.

Response fields

Field	Type	What it is
`key`	`string`	The key itself — for the first and last time.
`prefix`	`string`	The visible part for recognition in the list.

Refusal reasons

A rule refusal arrives as {"error":"rejected","refusal":{"kind":"…"}} with status 409. Refusals common to all endpoints are in the rules section.

Code	What happened and what to do
`key_no_name`	A key needs a name: in six months a list of unnamed keys is a list of identical strings.
`key_no_scopes`	A key with no scopes can do nothing. Tick the ones you need.
`key_too_many`	You already hold the maximum number of live keys. Revoke the ones you do not need: a hundred forgotten keys means the right one cannot be revoked.
`key_scope_escalation`	A key cannot grant scopes it does not hold itself. The refusal names the extra ones. A key with any scopes is issued from the cabinet by a human.

Nearby in this section

GET /api/v1/keys — My access keys
DELETE /api/v1/keys/{id} — Revoke a key