Issue an API key
Issues an API key (api-keys:manage), live at once, its grant: capabilities you hold, or any with users:manage (else 403 CAPABILITY_DENIED), never users:manage, api-keys:manage, notifications:manage, risk:propose, transfers:propose or any approve (422 INVALID_FIELD). Its secret comes once: the bearer is immix_<apiKeyId>_<secret>. A live key’s name refuses 409 NAME_TAKEN.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Required on every write: a URL-safe string of 1 to 64 characters from [A-Za-z0-9._~-] (a UUID fits), scoped to you. It names one operation on one record, ever: a retry replays the stored outcome (Idempotent-Replay: true) or attaches to the live one, and reuse on another record refuses 409 IDEMPOTENCY_KEY_REUSED. Missing or malformed, 400.
Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.
Query parameters
A position you hold — an X-Immix-Global-Sequence you read, or a 202’s commandGlobalSequence: this member answers only once it has folded the platform’s stream through it, waiting up to its deadline, then 503 PROJECTION_BEHIND with Retry-After. Within that stream a read is never older than what you have seen; drop your positions after an announced stream cut. A retry stating its 202’s position attaches to or replays that operation while the journal holds its key, never publishing twice. Stated once: one to nineteen digits, at most 9223372036854775807; else 400 MALFORMED_REQUEST.
Request
The key’s name, unique among the organisation’s live keys. At most 128 bytes; longer refuses INVALID_FIELD.
The bits the key holds from issue — any bit a member could hold but an approve bit, users:manage, api-keys:manage, risk:propose and transfers:propose (the risk writes name a member, and a transfer’s maker is one), notifications:manage (it approves an endpoint as well as proposing one) and the platform’s bit, and only bits the issuer holds unless it holds users:manage; the edge stores the set with the reads its verbs imply. a set (SBE bit-set) served as the array of its scope strings, each a Capability, in declared order; empty = none set, never null; as input a repeated name refuses 400
A capability preset the edge expands to its scope strings and never forwards — the row records the capabilities, never a preset. A key holds no users:manage, no api-keys:manage, no notifications:manage, no risk:propose, no transfers:propose and no approve capability: a preset or set naming one is refused 422 INVALID_FIELD. Preset or capabilities names the set, stored with the reads its verbs imply: the two must name one set once those reads are added, else 400.
Response
The API key as issued or rotated — its row, with the bearer the key presents under secret, served once: by this answer, or after a 202 as secret states; never cached by anything between the platform and you (Cache-Control: no-store) — with the answering change’s position, the row’s ETag and, on a replayed key, Idempotent-Replay.
What the key may do — the bits a member could hold, less what a key is never granted: an approve bit, users:manage, api-keys:manage, risk:propose and transfers:propose (the risk writes name a member, and a transfer’s maker is one) and the platform’s bit. A key granted transfers:propose before the grant was refused keeps it here and can use it nowhere. Stored with the reads its verbs imply. a set (SBE bit-set) served as the array of its scope strings, each a Capability, in declared order; empty = none set, never null; as input a repeated name refuses 400
Who issued the key — the api-keys:manage holder, a member. an actor: an object {kind, id}
The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
When the principal was last seen acting — its last admitted request on this API (one a read replica serves is not recorded), or its open trading socket — epoch nanoseconds at a five-minute grain: a request inside five minutes of the mark need not move it, so read it as active within five minutes of this time. null while no mark is recorded: the principal has not acted since marks were first kept (0.71.0), or ever. A mark beside the row, not a field of it: it moves no version and no ETag.
The key’s name — unique among the organisation’s live keys. At most 128 bytes; longer refuses INVALID_FIELD.
The organisation the key acts in — stamped by the owner from the issuer’s organisation, never client-supplied.
The bearer to present as Authorization: Bearer <secret> — immix_<apiKeyId>_<secret> — shown once: the platform keeps its digest alone, and no read or operation record serves it. After a 202, retry under the same Idempotency-Key as any write: the first accepted answer holding the secret the key’s row records serves it — normally the answer of the member that took the request. null on every other answer — a member that never held that secret, a replay once served, a key rotated since — and the remedy is a rotation (POST /api-keys/{id}/rotate): a fresh secret, served once.
UNKNOWN is the unset sentinel: outputs only — as input the field is required, and explicit UNKNOWN refuses 400. A consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
Who last rotated the key — the api-keys:manage holder its current secret was answered to, a member; null until the first rotation. The member behind what the key proposes from here on: a proposal it makes pins them as its record’s keyHolder, and neither they nor the key’s issuer may approve it (SELF_APPROVAL). an actor: an object {kind, id}; null where none is stated