> This page is for Trading.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.immix.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server.

# Disable a key

POST /accounts/{id}/keys/{keyId}/disable
Content-Type: application/json

Disables an active key at once (either `accounts` capability; 0.65.0): no proposal, no approval — the brake for a leaked or misbehaving key, acting with a proposal standing on the account — its connectors stop serving it, and enabling it again is a proposal. The answer is the account row, the key `DISABLED` in `keys[]`; the account's `version` does not move.

Reference: https://docs.immix.xyz/trading/api-reference/rest-api/venue-keys/disable-account-key

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `id` (integer, required) — The record's id — a positive 32-bit integer the platform minted.
- `keyId` (integer, required) — 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.

### Query parameters

- `minGlobalSequence` (string, optional) — 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`.

### Headers

- `Idempotency-Key` (string, required) — 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-Match` (string, required) — 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-Id` (string, optional) — 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.

### Body (application/json)

This endpoint expects an object.

- `credentialId` (integer, optional)
- `expectedVersion` (string, optional, nullable) — 0 = unconditional — the same deliberate sentinel as DisableAccount. int64 as a decimal JSON string

## Response

### 200

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

- `accountId` (integer, required) — Sticky entity key.
- `approvals` (list of AccountUpdatedApprovalsItem, required) — 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
- `capabilities` (AccountCapabilitySet, required) — 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.
- `concludedTransition` (enum, required) — 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
  - Allowed values: `NONE`, `ACTIVATE`, `AMEND`, `ENABLE`, `DELETE`, `ROTATE`, `RESUME_TRADING`, `KEY_CHANGE`
- `connection` (ConnectionReading, required, nullable) — 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`.
- `displayName` (string, required) — The account's name, as a person states it. At most 64 bytes; longer refuses INVALID_FIELD.
- `globalSequence` (string, required) — The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
- `keys` (list of AccountKey, required) — 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.
- `lastWithdrawalReason` (string, required) — Why the last proposal was withdrawn, as the withdrawer stated it; empty-not-null.
- `orgId` (integer, required) — The owning org — stamped by the owner from the maker's org, never client-supplied.
- `ownership` (enum, required) — 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: `UNKNOWN`, `HOUSE`, `CLIENT_OMNIBUS`, `CLIENT_SEGREGATED`
- `parentAccountId` (integer, required, nullable) — On a sub-account, the organisation's account for the parent the key probe stated (`parentExternalRef`), else null — derived at the read, never recorded.
- `parentExternalRef` (string, required) — 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.
- `pendingTransition` (enum, required) — 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
  - Allowed values: `NONE`, `ACTIVATE`, `AMEND`, `ENABLE`, `DELETE`, `ROTATE`, `RESUME_TRADING`, `KEY_CHANGE`
- `purpose` (enum, required) — 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
  - Allowed values: `UNKNOWN`, `TREASURY`, `CLIENT_DEPOSIT`, `SETTLEMENT_OPS`, `COLLATERAL`, `HEDGE`, `RAIL_VISIBLE`
- `readAtNs` (string, required, nullable) — 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.
- `remark` (string, required) — The maker's note on the pending proposal, for its approvers; empty-not-null. At most 256 bytes; longer refuses INVALID_FIELD.
- `status` (enum, required) — 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: `UNKNOWN`, `PENDING_APPROVAL`, `ACTIVE`, `DISABLED`, `DELETED`, `DRAFT`
- `trading` (ConnectionReading, required, nullable) — The order-entry connector's reading on the account's trading key; null when no key trades the account.
- `venueAccountRef` (string, required) — 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.
- `version` (string, required) — Monotonic per entity. int64 as a decimal JSON string
- `concludedAtNs` (string, optional, nullable) — 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
- `concludedBy` (Actor, optional, nullable) — 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
- `exchangeId` (integer, optional, nullable) — The venue the account is at — the exchange its keys are keys of.
- `keyHolder` (Actor, optional, nullable) — 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
- `lastWithdrawalAtNs` (string, optional, nullable) — 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
- `lastWithdrawalProposedBy` (Actor, optional, nullable) — Who made the last proposal that was withdrawn; null when none was. an actor: an object \{kind, id}; null where none is stated
- `lastWithdrawalWithdrawnBy` (Actor, optional, nullable) — 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
- `portfolioId` (integer, optional, nullable) — Single assignment in the POC; 0 = unassigned.
- `proposedAtNs` (string, optional, nullable) — 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
- `proposedBy` (Actor, optional, nullable) — 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 Disable Account Key Venue Keys Request Bad Request Error

Refused at the door — nothing reached the platform and the key was not journaled: a missing or malformed `Idempotency-Key`, a malformed `If-Match` (an absent one is 428 `PRECONDITION_REQUIRED`), malformed JSON, a body `actor` (or `userId`, its spelling before the actor), a body restating the path or `If-Match` differently, a money string off its `pattern` (an exponent, a plus sign, a bare point, surrounding whitespace) or past its `maxLength`, or one no value here can state (over 18 fractional digits, or past a 64-bit integer at its own scale), or any other value outside the schema.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 401 Disable Account Key Venue Keys Request Unauthorized Error

No bearer token, or one that does not verify.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 403 Disable Account Key Venue Keys Request Forbidden Error

`CAPABILITY_DENIED`: a read your capabilities do not cover, or a staging route without its propose bit (`accounts:propose`). `NOT_REGISTERED`: no row or open invitation at your verified address, an unknown organisation, or an unclaimed row (an administrator admits it). `EMAIL_UNVERIFIED`: verify, then sign in again. `INVITATION_EXPIRED`: an administrator re-invites. `FORBIDDEN_PRINCIPAL`: no `org_id`, a non-ASCII ref, a disabled user, a binding with no user. `ORG_NOT_ACTIVE`: disabled, pending or deleted. Owners' 403s carry the position header and `Idempotent-Replay`.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 404 Disable Account Key Venue Keys Request Not Found Error

No such row in your organisation — another organisation's row is indistinguishable from an absent one. The position header says as of when.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 409 Disable Account Key Venue Keys Request Conflict Error

The record owner's refusal, 409 for state or uniqueness and 422 for a field or reference, is a fact on the stream: it carries the position header and a retried key replays it. Door refusals ride the same statuses without the header, never journaled, so a retry takes fresh: 409 `IDEMPOTENCY_KEY_REUSED`; 422 `INSTRUMENT_NOT_LIVE` or `ACCOUNT_NOT_ACTIVE` on `POST /orders`, `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE` or `REFERENCE_UNKNOWN_ACCOUNT` in an algo document (every one answers a held key as its retry).

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 412 Disable Account Key Venue Keys Request Precondition Failed Error

`If-Match` is stale (`VERSION_CONFLICT`): the envelope carries `currentVersion` and the `ETag` header the current row — re-read, reapply, retry. A retried key replays it with `Idempotent-Replay`.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 413 Disable Account Key Venue Keys Request Content Too Large Error

The request is too large: a body declared past 1 MB (`PAYLOAD_TOO_LARGE`), or a command past the platform's own bound (`TOO_LARGE`, not expected for any route here). Nothing was submitted; a retry takes fresh.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 422 Disable Account Key Venue Keys Request Unprocessable Entity Error

The record owner's refusal, 409 for state or uniqueness and 422 for a field or reference, is a fact on the stream: it carries the position header and a retried key replays it. Door refusals ride the same statuses without the header, never journaled, so a retry takes fresh: 409 `IDEMPOTENCY_KEY_REUSED`; 422 `INSTRUMENT_NOT_LIVE` or `ACCOUNT_NOT_ACTIVE` on `POST /orders`, `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE` or `REFERENCE_UNKNOWN_ACCOUNT` in an algo document (every one answers a held key as its retry).

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 428 Disable Account Key Venue Keys Request Precondition Error

The entity write carries no `If-Match` (`PRECONDITION_REQUIRED`): refused at the door — nothing reached the platform and the key was not journaled. Send the `ETag` the row was read at, or `*` to write unconditionally on purpose, and send the request again under the same key.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 429 Disable Account Key Venue Keys Request Too Many Requests Error

Shed at once: `INBOX_FULL` or `IN_FLIGHT_FULL` (this member's bounds; nothing queued, the key not journaled), the intake's or the ticket route's `RATE_LIMITED`, or the orders owner's `RATE_CEILING` (the organisation's per-minute ceiling — a refusal on the stream, replayed like any, so its `retryable` is `false` and the order goes again under a fresh key). `Retry-After` says when.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 500 Disable Account Key Venue Keys Request Internal Server Error

The gateway failed to serve (`INTERRUPTED`, `INTERNAL_ERROR`, `PROJECTION_MISS`); the operation record, if one exists, is still readable.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

### 503 Disable Account Key Venue Keys Request Service Unavailable Error

This member cannot carry the write now: `NOT_PRIMED` (still catching up), `NOT_SERVING` (a read-only or not-ready member, or one that could not look the request's key up within the deadline), `OWNER_ABSENT` (the record owner has no active member), `INTAKE_UNAVAILABLE` (no credential store here), `REGISTRATION_PENDING` (your invitation's claim is in flight — retry after `Retry-After`), `PROJECTION_BEHIND` (behind your `If-Match` version or `minGlobalSequence` by the deadline), or the platform's own outcome for a command lost in transit. Nothing was journaled; retry against a serving member.

- `error` (ErrorBody, required) — What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
- `currentVersion` (string, optional) — On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance's config write: the row's current version (the `ETag` carries the same token) — re-read, reapply, retry.

## Types

### AccountUpdatedApprovalsItem

- `userId` (integer, required) — An approving user.
- `approvedAtNs` (string, optional, nullable) — Platform time of the approval. int64 as a decimal JSON string

### AccountCapabilitySet

One venue account is one row, with at most one key per role beneath it; each capability names the key that holds the role, or is null when no key does.

- `trade` (AccountCapability, required, nullable) — The key this account's orders instruct through, or null when the account's key does not trade — an account nothing can trade. Its `health` is that key's order-entry reading.
- `transfer` (AccountCapability, required, nullable) — The key this account's transfers execute through, or null when no transfers key is beneath the account — can't transfer: add one. Its `health` is that key's account reading: the account connector executes transfers.

### ConnectionReading

A reading beside a status: the venue's word through one key, and when it was last read cleanly.

- `status` (enum, required) — `CONNECTING` before any answer; then the key probe's verdict; then the connector's `ConnectionHealth.status` — all but the report that opens a lane's outage with a dial (`DOWN` with reason `STARTUP`, its `transitionAtNs` and `reportedAtNs` equal), which counts as none while the probe's verdict is clean or absent — a refused probe gets no such grace, its readings being `DOWN` either way; every later report counts, a redial's `STARTUP` included, and the key's own `health` keeps every report. The value set is append-only: treat an unknown name as `UNKNOWN`.
  - Allowed values: `CONNECTING`, `UNKNOWN`, `CONNECTED`, `DEGRADED`, `DOWN`
- `reason` (string, required) — A `HealthReason` name; `NONE` while nothing is wrong.
- `readAtNs` (string, required, nullable) — When the venue was last read cleanly through this key, by the same rule as the row's `readAtNs`; null until a report shows a clean read.

### AccountKey

One key beneath an account: its name, the roles and flags it holds, its lifecycle, each connector role's reading, what the probe observed, its rotation deadline and two audit handles — never the material or the store's reference. Since 0.70.0 the entry carries every field `PUT /accounts/{id}/keys/{keyId}` moves — `name`, `canReadBalances`, `canServeAddresses`, `rotateByNs` joining `trade` — on the image the view serves, so an approver reads a key change in the inbox item's two images without `venue-keys:read`; the key's own row stays that grant's.

- `keyId` (integer, required) — The key's id — `credentialId` on its own row.
- `version` (string, required) — The key's own version, as a decimal string — what a write to the key (`PUT /accounts/{id}/keys/{keyId}`, its `/rotate`, `/enable`, `/delete`, `/disable`) names in `If-Match`; the account row's `ETag` is the account's version, not this (0.65.0).
- `name` (string, required) — The key's name, unique among your organisation's live keys — what `PUT /accounts/{id}/keys/{keyId}` renames; on the latest view a pending rename's new name, on `?view=approved` the enforced one (0.70.0).
- `trade` (boolean, required) — Whether the key may place orders for the account.
- `transfer` (boolean, required) — Whether the key executes transfers out of the account — a dedicated key, which never trades.
- `canReadBalances` (boolean, required) — Whether the key reads the account's balances — `true` on every exchange key the gateway has created since every exchange key read (the create and the amend set it); a key pinned before that keeps its stated flag, which an amend restates (0.70.0).
- `canServeAddresses` (boolean, required) — Whether the key serves the account's deposit addresses — a flag an amend moves, so a change to it is read here by its approver (0.70.0).
- `status` (enum, required) — The key's lifecycle status — what an administrator decided; `ACTIVE` is the one that serves. The value set is append-only: treat an unknown name as `UNKNOWN`.
  - Allowed values: `UNKNOWN`, `DRAFT`, `PENDING_APPROVAL`, `ACTIVE`, `DISABLED`, `DELETED`
- `pendingTransition` (string, required) — The key's pending transition by name, `NONE` for none. A key stated at the connection rides the account's `ACTIVATE` (this reads `ACTIVATE` too); since 0.65.0 every later change to a key — added beneath a live account, amended, enabled, deleted or rotated — is the account's `KEY_CHANGE`, this reading the key's own act (`ACTIVATE`, `AMEND`, `ENABLE`, `DELETE`, `ROTATE`); the account's `/approve` and `/withdraw` settle both.
- `health` (CredentialHealthReadings, required) — One venue key is served by every connector role of its venue, and each role reports its own health of the key: the account connector (discovery, balances and the probe) and the order-entry connector (trading). A reading is null until that role has reported on the credential.
- `observed` (AccountKeyObserved, required) — What the key probe observed at the venue.
- `keyIdSuffix` (string, required) — The last four characters of the venue key id — enough to tell keys apart in a venue's console; empty at a venue whose key has no public id (`keyIdLeg` `null`), where `fingerprint` tells them apart.
- `fingerprint` (string, required) — The material's fingerprint, the audit handle behind `venue-keys:read`.
- `createdAtNs` (string, required, nullable) — When the venue issued the key, as stated when it was added; null when not stated.
- `rotateByNs` (string, required, nullable) — The deadline by which the key is to be rotated, epoch nanoseconds as a decimal string; null when none is set. An amend moves it, so a new deadline is read here by its approver (0.70.0).

### Actor

Who acted — the principal behind a command, a row's maker or its concluder: a member (USER, id = the user id), an API key the organisation issued (API_KEY, id = the API key id), or the platform itself (MACHINE, id 0 — a connector's report, an algo instance's order, the door's own write). The kind's value set is append-only: a consumer READING an unknown kind treats the actor as unknown, never as an error.

- `kind` (enum, required) — The kind of principal; which id space `id` names.
  - Allowed values: `USER`, `API_KEY`, `MACHINE`
- `id` (integer, required) — The principal's id in its kind's space: a user id, an API key id, or 0 for the platform itself.

### ErrorBody

What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.

- `code` (string, required) — The code to branch on — stable and open (before 1.0.0 a minor may remove one, its changelog naming it): treat one you do not know by its HTTP status. The gateway's: - 400: `MALFORMED_REQUEST`, `MISSING_IDEMPOTENCY_KEY`, `INVALID_IDEMPOTENCY_KEY`, `INVALID_IF_MATCH`, `INVALID_CURSOR` - 401: `UNAUTHENTICATED` - 403: `FORBIDDEN_PRINCIPAL`, `NOT_REGISTERED`, `INVITATION_EXPIRED`, `EMAIL_UNVERIFIED`, `ORG_NOT_ACTIVE`, `CAPABILITY_DENIED` - 404: `NOT_FOUND`, `UNKNOWN_OPERATION`, `ROUTE_NOT_FOUND` (no route answers the path) - 405: `METHOD_NOT_ALLOWED` - 409: `IDEMPOTENCY_KEY_REUSED`, `INTAKE_KEY_REUSED`, `KEY_ALREADY_REGISTERED`, `CONNECTION_DOWN` (`POST /transfers`), `EXCEEDS_MARGIN_HEADROOM`, `HEADROOM_UNKNOWN` (a transfer's submit and its approval) - 413: `TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `DOCUMENT_TOO_LARGE` - 422: a reference this member will not send: `INSTRUMENT_NOT_LIVE`, `ACCOUNT_NOT_ACTIVE` (`POST /orders`), `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE`, `REFERENCE_UNKNOWN_ACCOUNT` (an algo document); `VENUE_UNSUPPORTED`, `DEDICATED_KEY`, `DESTINATION_NOT_ALLOWED` - 428: `PRECONDITION_REQUIRED` - 429: `INBOX_FULL`, `IN_FLIGHT_FULL`, `RATE_LIMITED` - 500: `INTERRUPTED`, `INTERNAL_ERROR`, `PROJECTION_MISS` - 503: `NOT_PRIMED`, `NOT_SERVING`, `OWNER_ABSENT`, `INTAKE_UNAVAILABLE`, `BALANCES_UNAVAILABLE`, `POSITIONS_UNAVAILABLE`, `RISK_UNAVAILABLE`, `TRANSFERS_UNAVAILABLE`, `ALGOS_UNAVAILABLE`, `NOTIFICATIONS_UNAVAILABLE`, `TICKETS_UNAVAILABLE`, `REGISTRATION_PENDING`, `PROJECTION_BEHIND`, `LOST`, `REJECTED_NOT_REGISTERED`, `REJECTED_NOT_ACTIVE` The record owners' refusals ride verbatim — `OrgRegisterRejected.reason`, `OrderRejected.reason`, `AlgoRejected.reason`, `RiskLimitRejectReason`, `RiskAdjustmentRejectReason`, `ManualExecutionRejectReason`, `TransferRejectReason` and `NotificationEndpointRejected.reason` list them; the guide maps each to its status.
- `message` (string, required) — For display only; its wording may change at any time.
- `requestId` (string, required) — The request's id, also sent as X-Request-Id; quote it to support.
- `retryable` (boolean, required) — Whether sending the identical request again, its `Idempotency-Key` included, after `Retry-After` or a short pause, can succeed with nothing else changed. `false` where something must change first: the request, its key, its precondition, the caller's standing, or the platform's own records or deployment. A refusal the record owner judged is always `false`: it is the recorded answer to its key, which replays it.

### AccountCapability

A key holding one of the account's roles: which credential, its lifecycle status, and the latest report from the connector that fills the role.

- `credentialId` (integer, required) — The credential that holds the role.
- `status` (enum, required) — The key's lifecycle status — what an administrator decided; `ACTIVE` is the one that serves. The value set is append-only: treat an unknown name as `UNKNOWN`.
  - Allowed values: `UNKNOWN`, `DRAFT`, `PENDING_APPROVAL`, `ACTIVE`, `DISABLED`, `DELETED`
- `health` (ConnectionHealth, required, nullable) — The role's latest reading, or null when its connector has not reported on the key. Judge it by its `reportedAtNs`, as a credential's `health`.

### CredentialHealthReadings

One venue key is served by every connector role of its venue, and each role reports its own health of the key: the account connector (discovery, balances and the probe) and the order-entry connector (trading). A reading is null until that role has reported on the credential.

- `account` (ConnectionHealth, required, nullable) — The account connector's latest report, or null when no account connector has reported on the credential.
- `trading` (ConnectionHealth, required, nullable) — The order-entry connector's latest report, or null when none has reported on the credential — every key that does not trade.

### AccountKeyObserved

What the key probe observed at the venue.

- `permissions` (list of string, required) — The venue's permissions on the key as the probe read them, in choice order (`read`, `trade`, `withdraw`); empty until a probe answers.
- `allowlist` (string, required) — The probe's verdict on the key's IP allowlist, by name; `UNKNOWN` until a probe answers.
- `outcome` (string, required) — The probe's outcome, a `HealthReason` name: `NONE` for a clean answer, `UNKNOWN` until one, else why it failed (`IP_NOT_WHITELISTED`, `AUTH_FAILED`, `ACCOUNT_EXISTS`, `CONFIG_ERROR`, …).
- `probedAtNs` (string, required, nullable) — When the probe last answered, epoch nanoseconds; null until one has.
- `scopeUnobserved` (boolean, required) — `true` = the probe answered but its venue serves no read of the key's own scope (Binance Demo Mode has no `/sapi`), so `permissions` is empty because nothing stated it and the approval's scope edges are not applied; `false` = the scope, as observed, is the venue's word and is judged.

### ConnectionHealth

- `credentialId` (integer, required) — The credential the report is about.
- `status` (enum, required) — Whether a connector is serving the credential: CONNECTED serves, DEGRADED serves impaired, DOWN does not serve, dialing and redialing included. 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: `UNKNOWN`, `CONNECTED`, `DEGRADED`, `DOWN`
- `reason` (enum, required) — Why the status is what it is; NONE when nothing is wrong. 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: `UNKNOWN`, `NONE`, `AUTH_FAILED`, `IP_NOT_WHITELISTED`, `PERMISSION_DENIED`, `RATE_LIMITED`, `VENUE_UNREACHABLE`, `STARTUP`, `RECONNECT`, `HEARTBEAT_TIMEOUT`, `VENUE_MAINTENANCE`, `BACKPRESSURE`, `RESYNC`, `SHUTDOWN`, `FAILOVER`, `LAGGING`, `RECOVERED`, `INVALID_KEY`, `CLOCK_SKEW`, `CONFIG_ERROR`, `STREAM_STALE`, `VENUE_UNAVAILABLE`, `ACCOUNT_EXISTS`, `ACCOUNT_DISABLED`
- `sinceNs` (string, required) — When the current status and reason began, on the connector's own clock. int64 as a decimal JSON string
- `transitionAtNs` (string, required) — Platform time the current status began. A restatement leaves it, and so does a change of reason alone, so the time since it is how long the credential has been in this status. int64 as a decimal JSON string
- `reportedAtNs` (string, required) — Platform time of the latest report. A connector serving the credential restates its report on a heartbeat, so a time that stops advancing means nothing is reporting on it any more. int64 as a decimal JSON string
- `role` (enum, required) — Which connector role this reading is from: ACCOUNT (balances, the probe) or ORDER_ENTRY (trading). A credential has one reading per role and exchange. 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: `UNKNOWN`, `ACCOUNT`, `ORDER_ENTRY`
- `detail` (string, required) — What the connector or the venue said, for people: display it, do not parse it. Empty when there is nothing to add. At most 512 bytes (the connector clips what the venue said to that).
- `venueRoundTripNs` (string, optional, nullable) — The latest round trip to the venue the connector measured; 0 = not measured. int64 as a decimal JSON string
- `exchangeId` (integer, optional, nullable) — The exchange this reading is from: the key's own, or a further one its venue trades — a Binance key's spot (100) and USD-M (102) order-entry readings are two. Every reading names its exchange.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "accountId": 1,
  "approvals": [
    {
      "userId": 1,
      "approvedAtNs": "approvedAtNs"
    }
  ],
  "capabilities": {
    "trade": {
      "credentialId": 1,
      "status": "UNKNOWN",
      "health": {
        "credentialId": 1,
        "status": "UNKNOWN",
        "reason": "UNKNOWN",
        "sinceNs": "sinceNs",
        "transitionAtNs": "transitionAtNs",
        "reportedAtNs": "reportedAtNs",
        "role": "UNKNOWN",
        "detail": "detail"
      }
    },
    "transfer": {
      "credentialId": 1,
      "status": "UNKNOWN",
      "health": {
        "credentialId": 1,
        "status": "UNKNOWN",
        "reason": "UNKNOWN",
        "sinceNs": "sinceNs",
        "transitionAtNs": "transitionAtNs",
        "reportedAtNs": "reportedAtNs",
        "role": "UNKNOWN",
        "detail": "detail"
      }
    }
  },
  "concludedTransition": "NONE",
  "connection": {
    "status": "CONNECTING",
    "reason": "reason",
    "readAtNs": "readAtNs"
  },
  "displayName": "displayName",
  "globalSequence": "globalSequence",
  "keys": [
    {
      "keyId": 1,
      "version": "version",
      "name": "name",
      "trade": true,
      "transfer": true,
      "canReadBalances": true,
      "canServeAddresses": true,
      "status": "UNKNOWN",
      "pendingTransition": "pendingTransition",
      "health": {
        "account": null,
        "trading": null
      },
      "observed": {
        "permissions": [
          "permissions"
        ],
        "allowlist": "allowlist",
        "outcome": "outcome",
        "probedAtNs": null,
        "scopeUnobserved": true
      },
      "keyIdSuffix": "keyIdSuffix",
      "fingerprint": "fingerprint",
      "createdAtNs": "createdAtNs",
      "rotateByNs": "rotateByNs"
    }
  ],
  "lastWithdrawalReason": "lastWithdrawalReason",
  "orgId": 1,
  "ownership": "UNKNOWN",
  "parentAccountId": 1,
  "parentExternalRef": "parentExternalRef",
  "pendingTransition": "NONE",
  "purpose": "UNKNOWN",
  "readAtNs": "readAtNs",
  "remark": "remark",
  "status": "UNKNOWN",
  "trading": {
    "status": "CONNECTING",
    "reason": "reason",
    "readAtNs": "readAtNs"
  },
  "venueAccountRef": "venueAccountRef",
  "version": "version",
  "concludedAtNs": "concludedAtNs",
  "concludedBy": {
    "kind": "USER",
    "id": 1
  },
  "exchangeId": 1,
  "keyHolder": {
    "kind": "USER",
    "id": 1
  },
  "lastWithdrawalAtNs": "lastWithdrawalAtNs",
  "lastWithdrawalProposedBy": {
    "kind": "USER",
    "id": 1
  },
  "lastWithdrawalWithdrawnBy": {
    "kind": "USER",
    "id": 1
  },
  "portfolioId": 1,
  "proposedAtNs": "proposedAtNs",
  "proposedBy": {
    "kind": "USER",
    "id": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/accounts/1/keys/1/disable"

payload = {}
headers = {
    "Idempotency-Key": "Idempotency-Key",
    "If-Match": "If-Match",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/accounts/1/keys/1/disable';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'Idempotency-Key',
    'If-Match': 'If-Match',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/accounts/1/keys/1/disable"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "Idempotency-Key")
	req.Header.Add("If-Match", "If-Match")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/accounts/1/keys/1/disable")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'Idempotency-Key'
request["If-Match"] = 'If-Match'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.example.com/accounts/1/keys/1/disable")
  .header("Idempotency-Key", "Idempotency-Key")
  .header("If-Match", "If-Match")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/accounts/1/keys/1/disable', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'Idempotency-Key',
    'If-Match' => 'If-Match',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/accounts/1/keys/1/disable");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "Idempotency-Key");
request.AddHeader("If-Match", "If-Match");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "Idempotency-Key",
  "If-Match": "If-Match",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/accounts/1/keys/1/disable")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```