Skip to navigation

Rotate a credential's key

Proposes new key material (accounts:propose) — a change on the account’s slot (0.65.0): the body carries the material once; the answer is the account row, KEY_CHANGE pending (at an accounts count of 0, concluded at once), the incoming key’s fingerprint and observed in keys[]; POST /accounts/{id}/approve cuts the connectors over to it. Staged again, it replaces its own change.

Authentication

AuthorizationBearer

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

Path parameters

idintegerRequired

The record’s id — a positive 32-bit integer the platform minted.

keyIdintegerRequired

The key’s id beneath the account — keyId on the account row’s keys[], credentialId on its own row; a key of another account is 404.

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.

If-MatchstringRequired

Required on every entity write: the ETag the read minted, quoted or bare — the version this write was computed against — or * to write unconditionally on purpose, except on a notification endpoint’s approval, which refuses * 400 INVALID_IF_MATCH. Absent is 428 PRECONDITION_REQUIRED; a weak validator 400 INVALID_IF_MATCH; a stale value 412 VERSION_CONFLICT (CONFIG_SEQ_CONFLICT on an algo’s config write) with currentVersion and a fresh ETag: re-read, reapply, retry. A * write overwrites every field from your copy, a colleague’s amend since your read included.

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

The venue key’s material, sent once over TLS and never served back: the gateway stores it write-only, fingerprints it and fills venueKeyId from the venue’s key-id leg (empty: it has none). One schema per venue: exchangeId names the venue and the material carries exactly its legs, each a non-blank string; a leg’s refusal names material.<leg>. x-immix-intake-venues lists each venue’s legs, key-id leg, connectors (a null accountGroup: balances-only keys refused, VENUE_UNSUPPORTED) and markets, further exchanges its key trades; GET /venue-key-specs serves them with form hints.

credentialIdintegerOptional
expectedVersionstring or nullOptionalformat: "^-?[0-9]+$"
int64 as a decimal JSON string
keyCreatedAtNsstring or nullOptionalformat: "^-?[0-9]+$"
int64 as a decimal JSON string
rotateByNsstring or nullOptionalformat: "^-?[0-9]+$"
int64 as a decimal JSON string
remarkstringOptional

A note for the approvers of this proposal; empty-not-null. At most 256 bytes; longer refuses INVALID_FIELD. Optional in this body: absent reads as "".

Response

The account as the platform now holds it after the write — the account’s own, or (0.65.0) one of its keys’ — the same row the read serves, with the answering change’s position, the account’s ETag (what a key’s write never takes in If-Match: that is keys[].version), on a key write Location (the key’s own route) and, on a replayed key, Idempotent-Replay.

accountIdinteger
Sticky entity key.
approvalslist of objects

Who approved the row’s last proposal and when, in approval order — grown by each approval and kept on the concluded row as its record until the next proposal or a withdrawal clears it; empty until the first approval. The proposal concludes at the approval that meets the organisation’s count for the family as it stands then; pendingTransition says whether one is pending. a repeating group served as an array of objects, in the group’s own order; empty = no entries, never null

capabilitiesobject

Derived from the keys beneath the account (keys[]) as enforcement reads them: trade is the account’s own key where it trades, transfer its transfers key — a pending key changes nothing here until it is approved. It is derived, not decided: it changes with the keys’ records and their health without the row’s version moving, and it reads the same on both views.

concludedTransitionenum

What the row’s last proposal proposed, kept once it concluded: the pending transition the conclusion cleared, as the register wrote it (KEY_CHANGE, since v21, a key’s change — the key’s own concludedTransition says which); NONE while it pends, or where none was. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict

connectionobject or null

The account’s reading through the key that reads it (its own key while ACTIVE, else its transfers key standing in): CONNECTING until the first answer, then the probe’s or the connector’s word — CONNECTED, DEGRADED or DOWN with its reason (IP_NOT_WHITELISTED, AUTH_FAILED, ACCOUNT_EXISTS when another live account of the organisation already holds that venue account, ACCOUNT_DISABLED, …). A DOWN reading stays on the row for the member to read, and the periodic re-probe recovers it once the venue answers. Null once the account is DELETED.

displayNamestring

The account’s name, as a person states it. At most 64 bytes; longer refuses INVALID_FIELD.

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

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

keyslist of objects

The account’s live keys, ascending by keyId, never a deleted one; GET /accounts/{id}/keys/{keyId} serves the whole row. On the latest view each key’s latest image: a change pending on the account’s slot (pendingTransition KEY_CHANGE, 0.65.0) shows as the key’s own transition and image — a rotation’s incoming fingerprint and observed, an amend’s name, flags and rotateByNs (0.70.0), an enable, a delete, a new key. On ?view=approved each key as enforcement reads it; the two agree while nothing pends. Readings move without the row’s version; a key change moves it.

lastWithdrawalReasonstring

Why the last proposal was withdrawn, as the withdrawer stated it; empty-not-null.

orgIdinteger

The owning org — stamped by the owner from the maker’s org, never client-supplied.

ownershipenum

Whose value the account holds; HOUSE unless stated otherwise. 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:
parentAccountIdinteger or null

On a sub-account, the organisation’s account for the parent the key probe stated (parentExternalRef), else null — derived at the read, never recorded.

parentExternalRefstring

The venue’s identifier for the account this one is a sub-account of, as the key probe stated it; empty for a main account, or until a probe answers. The organisation’s row for it, where one exists, is served beside it as parentAccountId. At most 256 bytes; longer refuses INVALID_FIELD.

pendingTransitionenum

ACTIVATE (the connection), AMEND (a re-statement — the proposed axes ride this record while the last approved record keeps enforcing), ENABLE, DELETE, KEY_CHANGE (since v21 a change to one of the account’s keys — added, amended, rotated, enabled or deleted; the key’s own pendingTransition says which); NONE otherwise. NONE is the unset sentinel: outputs only — as input the field is required, and explicit NONE refuses 400. A consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict

purposeenum

What the account is for; TREASURY unless stated otherwise. 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

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

When the account was last read: the latest account report on the key that reads it (the account’s own key while ACTIVE, else its transfers key standing in) — its health.account.reportedAtNs while CONNECTED, or DEGRADED for a reason other than RATE_LIMITED and VENUE_UNAVAILABLE, and only after the status’s first report (transitionAtNs); null otherwise — DOWN, those two, unreported — and once DELETED. The one clock to age for an account: a time that stops is a connector stopped silently; null: the report shows no clean read, health.account saying why.

remarkstring

The maker’s note on the pending proposal, for its approvers; empty-not-null. At most 256 bytes; longer refuses INVALID_FIELD.

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

tradingobject or null

The order-entry connector’s reading on the account’s trading key; null when no key trades the account.

venueAccountRefstring

The venue’s own identifier for this account (an OKX uid, a Bybit UID), filled by the first key probe that answers; empty until then. Unique among the organisation’s live accounts at the venue. At most 256 bytes; longer refuses INVALID_FIELD.

versionstringformat: "^-?[0-9]+$"
Monotonic per entity. int64 as a decimal JSON string
concludedAtNsstring or nullOptionalformat: "^-?[0-9]+$"

Platform time the row’s last proposal concluded; 0 while it is pending, or when the row never carried one. A write the organisation’s count let through at once concludes in the maker’s own fact: equal to proposedAtNs. int64 as a decimal JSON string

concludedByobject or nullOptional

Who concluded the row’s last proposal: the approver whose approval met the organisation’s count, or the maker when the count was 0 and the write concluded at once; null while it is pending, or when the row never carried one. an actor: an object {kind, id}; null where none is stated

exchangeIdinteger or nullOptional

The venue the account is at — the exchange its keys are keys of.

keyHolderobject or nullOptional

When an API key made the row’s last proposal, the member the key’s secret had last been answered to as it proposed — its last rotator then, else its issuer — kept on the concluded row with proposedBy; null when a member made the proposal, or the row never carried one. The proposal counts as this member’s and the key’s issuer’s, whoever rotates the key afterwards: neither may approve it (SELF_APPROVAL). an actor: an object {kind, id}; null where none is stated

lastWithdrawalAtNsstring or nullOptionalformat: "^-?[0-9]+$"

Platform time of that withdrawal; 0 when none was. The three fields and lastWithdrawalReason stand until the next proposal replaces them. int64 as a decimal JSON string

lastWithdrawalProposedByobject or nullOptional

Who made the last proposal that was withdrawn; null when none was. an actor: an object {kind, id}; null where none is stated

lastWithdrawalWithdrawnByobject or nullOptional

Who withdrew it — the proposer, or a checker returning it; null when none was. an actor: an object {kind, id}; null where none is stated

portfolioIdinteger or nullOptional

Single assignment in the POC; 0 = unassigned.

proposedAtNsstring or nullOptionalformat: "^-?[0-9]+$"

Platform time the row’s last proposal was made, kept on the concluded row; 0 when the row never carried one. int64 as a decimal JSON string

proposedByobject or nullOptional

Who made the row’s last proposal — kept on the concluded row as its record; null when the row never carried one. pendingTransition says whether that proposal is still pending. an actor: an object {kind, id}; null where none is stated

Errors

400
Rotate Account Key Venue Keys Request Bad Request Error
401
Rotate Account Key Venue Keys Request Unauthorized Error
403
Rotate Account Key Venue Keys Request Forbidden Error
404
Rotate Account Key Venue Keys Request Not Found Error
409
Rotate Account Key Venue Keys Request Conflict Error
412
Rotate Account Key Venue Keys Request Precondition Failed Error
413
Rotate Account Key Venue Keys Request Content Too Large Error
422
Rotate Account Key Venue Keys Request Unprocessable Entity Error
428
Rotate Account Key Venue Keys Request Precondition Error
429
Rotate Account Key Venue Keys Request Too Many Requests Error
500
Rotate Account Key Venue Keys Request Internal Server Error
503
Rotate Account Key Venue Keys Request Service Unavailable Error