Idem API Key Scopes and Least-Privilege Access Control

Every API key issued to your tenant carries one or more scopes that define exactly which endpoints and operations that key can perform. Scopes follow the principle of least privilege — you should grant each integration only the permissions it genuinely needs. A payment processor that posts transactions has no business reading compliance exports, and an automated agent that executes trades should not be able to create new accounts. Keeping scopes narrow limits the blast radius if a key is ever compromised.

Scope reference

The table below lists every available scope and the endpoints it unlocks.

Scope	Endpoints unlocked
`TRANSACTIONS_READ`	List transactions, get transaction by ID, list settlements, get settlement by ID
`TRANSACTIONS_WRITE`	Post transactions, register settlements, cancel settlements
`ACCOUNTS_READ`	List accounts, get account by ID, get balance, list journal entries, get account statement
`ACCOUNTS_WRITE`	Create accounts
`AGENTS_EXECUTE`	Execute agent-originated transactions
`AGENTS_ROLLBACK`	Roll back agent transactions
`AGENTS_AUDIT_READ`	Read agent audit records
`RECONCILIATION_READ`	Read reconciliation results and status
`RECONCILIATION_WRITE`	Trigger batch reconciliation runs
`COMPLIANCE_EXPORT`	Export the full audit log as NDJSON
`WEBHOOK_MANAGE`	Get and update webhook configuration
`ADMIN`	Create, list, and revoke API keys; manage policy rules; supersedes all other scopes

Recommended scope sets

Different integration patterns call for different scope combinations. The examples below cover the most common cases.

Read-only integration

For dashboards, analytics pipelines, or any consumer that only needs to observe ledger state.

TRANSACTIONS_READ
ACCOUNTS_READ

Payment processor

For services that accept payments, post transactions, and manage accounts.

TRANSACTIONS_WRITE
ACCOUNTS_READ
ACCOUNTS_WRITE

Compliance team

For audit and compliance workflows that need a full export of ledger activity.

COMPLIANCE_EXPORT
ACCOUNTS_READ

Automated agent

For AI agents or automated systems that execute and review transactions on your behalf.

AGENTS_EXECUTE
TRANSACTIONS_READ
ACCOUNTS_READ

Creating a scoped key

Send a POST request to /api/v1/api-keys with an array of the scopes you want the new key to carry. This endpoint requires the ADMIN scope on your calling key.

POST /api/v1/api-keys
{
  "scopes": [
    "TRANSACTIONS_WRITE",
    "ACCOUNTS_READ",
    "ACCOUNTS_WRITE"
  ]
}

Idem does not support naming keys — scopes is the only request field. Track which key is which by its prefix (see below), or by which integration you issued it to.

Response — 201 Created

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "rawKey": "sk_live_...",
  "prefix": "sk_live_abc1",
  "scopes": [
    "TRANSACTIONS_WRITE",
    "ACCOUNTS_READ",
    "ACCOUNTS_WRITE"
  ],
  "createdAt": "2024-01-15T10:00:00Z"
}

The rawKey field is returned only once at creation time. Store it securely in your secrets manager immediately — it cannot be retrieved again. If a key is lost, revoke it and issue a replacement.

The ADMIN scope supersedes all other scopes: a key carrying ADMIN can perform every operation in the API, including issuing and revoking other keys and modifying policy rules. Reserve ADMIN keys exclusively for administrative tooling such as key provisioning scripts and infrastructure automation. Never use an ADMIN-scoped key in transactional workloads, application servers, or anywhere the key could be exposed to a broader attack surface.

Get Started

Core Concepts

Guides

Idem API Key Scopes and Least-Privilege Access Control

Scope reference

Recommended scope sets

Read-only integration

Payment processor

Compliance team

Automated agent

Creating a scoped key

​Scope reference

​Recommended scope sets

Read-only integration

Payment processor

Compliance team

Automated agent

​Creating a scoped key

Scope reference

Recommended scope sets

Creating a scoped key