Skip to navigation

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringRequired

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.

X-Request-IdstringOptional

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

minGlobalSequencestringOptionalformat: "^[0-9]{1,19}$"

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

This endpoint expects an object.
namestringRequired

The key’s name, unique among the organisation’s live keys. At most 128 bytes; longer refuses INVALID_FIELD.

capabilitieslist of enumsOptional

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

presetenumOptional

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.

Allowed values:

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.

apiKeyIdinteger
Sticky entity key.
capabilitieslist of enums

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

createdAtNsstringformat: "^-?[0-9]+$"
Platform time the key was issued, epoch nanoseconds. int64 as a decimal JSON string
createdByobject

Who issued the key — the api-keys:manage holder, a member. an actor: an object {kind, id}

globalSequencestringformat: "^[0-9]+$"

The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.

lastActiveAtNsstring or nullformat: "^[0-9]+$"

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.

namestring

The key’s name — unique among the organisation’s live keys. At most 128 bytes; longer refuses INVALID_FIELD.

orgIdinteger

The organisation the key acts in — stamped by the owner from the issuer’s organisation, never client-supplied.

secretstring or null

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.

statusenum

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

Allowed values:
versionstringformat: "^-?[0-9]+$"
Monotonic per entity. int64 as a decimal JSON string
rotatedByobject or nullOptional

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

Errors

400
Issue API Keys Request Bad Request Error
401
Issue API Keys Request Unauthorized Error
403
Issue API Keys Request Forbidden Error
409
Issue API Keys Request Conflict Error
413
Issue API Keys Request Content Too Large Error
422
Issue API Keys Request Unprocessable Entity Error
429
Issue API Keys Request Too Many Requests Error
500
Issue API Keys Request Internal Server Error
503
Issue API Keys Request Service Unavailable Error