Create a project key

Creates a key of the project with the given scopes and records key.created. The answer carries the key string, once. An admin key may create one in any live project; a project key needs scope keys, works in its own project only, and grants only scopes it holds (and, if it expires, no later expiry).

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

CreateApiKeyRequest object
namestringrequired

What the key is for: 1 to 128 characters, trimmed.

example billing backend
scopesarray of Scoperequired

What the key may do: at least one scope, each once. A project key grants only scopes it holds itself.

example ["read","write"]
expires_atstring · date-time | null

When the key stops working, RFC 3339, later than now; null or left out: never. A project key that expires grants no later expiry.

example 2027-01-01T00:00:00Z

Responses

201

The key and its key string, shown this once

Header	Type	Description
`Cache-Control`	string	`no-store`
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.
`Location`	string	The key’s URL (`DELETE` revokes it)

CreatedApiKey object · all fields required
created_atstring · date-time
expires_atstring · date-time | null
idstring · uuid
keystring | null

The key string to send as Authorization: Bearer. It is not stored and no other answer shows it: keep it now. null in a replay (Idempotent-Replayed: true) of a request sent again with the same Idempotency-Key: the key was created by the first request, whose answer carried its string; revoke it and create another with a new Idempotency-Key if that answer was lost.

example pw_prj_1a2b3c4d_...
kindApiKeyKind

The kind of an API key.
- admin
- project
last_used_atstring · date-time | null
namestring
prefixstring
project_idstring · uuid | null
revoked_atstring · date-time | null
scopesarray of Scope

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope keys, or granting more than it holds (forbidden)

Problem (application/problem+json)

404

No such project, or another project’s (not_found)

Problem (application/problem+json)

409

The project is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed); or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)