Authentication

How to authenticate with the Bitnob Enterprise API and how authorization decisions are made.

Every request to the Enterprise API is authenticated with an API key. Keys are issued from the Bitnob dashboard and carry a permission set that is bound to your organisation at issue time.

Sending Your API Key

Pass your key on the X-API-Key header with every request:

Required Headers

The organisation context is resolved automatically from the key — you never need to send an org ID header. Keep keys server-side. A leaked key grants the same authority a signed-in admin user does, up to the limits of its permission set and configured policies.

Keep keys server-side

Never expose an Enterprise API key in a mobile app, frontend JavaScript bundle, or public repository. All signing should happen in your backend.

Required Headers

header	required	description
X-API-Key	Yes	Your API key. Organisation is derived from the key automatically.
X-API-VERSION	No	API version. Defaults to v1 if not supplied.
Content-Type	For writes	Must be application/json for all POST, PUT, and PATCH requests.

How Authorization Works

API key calls never receive a WebAuthn or MFA challenge. When the key has the required permission and the request passes every configured policy, the Bitnob Secure Enclave signs synchronously.

The authorization flow for every transaction is:

API key is verified. The key must exist, be active, and carry the permission required for the requested operation.

Policies are evaluated. Every active policy is checked against the transaction parameters — spending limits, address whitelists, velocity caps, and approval thresholds all run before signing.

Enclave signs or holds. If every policy passes, the Enclave signs immediately. If a policy fires require_approval, the transaction is held in pending_authorization until approvers vote.

Transaction is broadcast. After signing, the transaction is broadcast to the network. If gas sponsorship is needed, the gas station tops up the wallet first.

A leaked key cannot exfiltrate funds beyond what its policies permit. Spending limits, address whitelists, velocity caps, and approval quorums all enforce constraints independently of the key's permission set.

API Versioning

The Enterprise API supports two versioning strategies. Both are valid and can be used interchangeably.

Header-based (recommended)

Header-Based Versioning

Path-based

Path-Based Versioning

Routes in the API reference are shown without a version prefix. Prepend /v1/ or set the X-API-VERSION: v1 header as needed.

Idempotency

All mutation endpoints that create resources (vaults, wallets, transactions) require an idempotency_key in the request body. This is a client-generated string of 1–64 characters that identifies the request uniquely.

If a request succeeds, resubmitting the same idempotency_key returns the original result without re-executing

If the original request is still in-flight, resubmitting returns 409 Conflict

Use UUIDs or a composite key (e.g., withdrawal-cust12345-001) to ensure global uniqueness

Safe retries under network failures

Always include an idempotency_key so you can safely retry a timed-out request without risk of creating duplicate transactions.