Zaira Auth

All requests require the x-api-key header for authentication (except /health).

API key

Include your API key in every request:

x-api-key: your-api-key

Contact the Zaira team to receive your API key.

User identity

After authentication, most endpoints require user identification. Use the user_uuid returned from /initiate:

x-user-uuid: <user-uuid>

Connecting a user at /initiate

/initiate is where you tell Zaira who it is talking to. Every call needs both x-api-key and x-bakkt-api-key; what you add alongside them decides which kind of user you get.

ScenarioHeadersWhat Zaira does
New userx-api-key
x-bakkt-api-key
Registers a brand-new user that onboards through Zaira from scratch.
Existing Bakkt user, custodial walletx-api-key
x-bakkt-api-key
x-bakkt-custodial-wallet-uuid
Signs in with the wallet, resolves the Bakkt user, and links the wallet to the Zaira user.
Existing Bakkt user, self-custodyx-api-key
x-bakkt-api-key
x-bakkt-session-id
Resolves the Bakkt user from the session and acts through that session.

In all three cases the response is the same: the Zaira user_uuid.

Why two different credentials

Zaira needs a way to act on the user's behalf, and there are exactly two:

  • x-bakkt-custodial-wallet-uuid — the wallet is held by Bakkt, so Zaira can sign with it. Signing in with the wallet is itself the proof that you are entitled to it. This is the stronger capability: these users can execute transfers.
  • x-bakkt-session-id — the user holds their own wallet, so Zaira cannot sign for them. Instead it acts through the user's own Bakkt session. These users can manage beneficiaries and retrieve payout details, but Zaira will not execute transfers for them.

If you supply both, the custodial wallet takes precedence.

Rules

  • x-bakkt-api-key is always required, including for brand-new users.
  • To connect an existing Bakkt user, add either x-bakkt-custodial-wallet-uuid or x-bakkt-session-id. Omit both to register a new user.
  • You do not send the Bakkt user UUID. Zaira retrieves the user's Bakkt identity directly from Bakkt using the wallet or session you supplied.
  • If a user holds a custodial wallet, send x-bakkt-custodial-wallet-uuid. It is what enables Zaira to execute transfers for them; connecting them with a session ID alone sets them up as a self-custody user instead.

Optional ip_address

POST /initiate accepts an optional JSON body. The only supported field is ip_address, the user's client IP (IPv4 or IPv6):

{
  "ip_address": "203.0.113.1"
}
🚧

Self-custody wallet funding requires a stored IP

ip_address is not required to initiate a user. Omit it and initiation still succeeds; balances, history, fees, beneficiaries, and other supported self-custody capabilities remain available.

Wallet funding does not. For a US self-custody user with no stored IP, Zaira will not start a funding journey (linking a bank account or pulling funds into the wallet). This is separate from sending a transfer to a beneficiary: self-custody users still never have Zaira execute that transfer — they sign and send it themselves. Missing IP only turns funding off.

If a US self-custody user asks to fund their wallet and no IP is stored, Zaira returns this fixed message instead of calling any funding tools:

Wallet funding isn't available for your account right now. Please contact your app provider for help.

Store the IP on /initiate. Sending it only on /ask or /ask/stream does not persist it and does not enable funding.

Calling /initiate again for an existing user can change the stored IP without changing the user's identity or custody type:

BodyEffect
{ "ip_address": "203.0.113.1" }Set or overwrite the stored IP.
{ "ip_address": null }Clear the stored IP. Funding becomes unavailable for self-custody users.
{} or no bodyLeave any stored IP unchanged.

Omitting the field never clears an existing IP. If the field is present, it must be a non-empty IP string or null.

Failure cases

StatusCause
400x-bakkt-api-key is missing.
400x-bakkt-custodial-wallet-uuid is not a valid UUID.
400The custodial wallet does not exist.
400The Bakkt user belongs to a different Zaira merchant.
400ip_address is present but is not a non-empty string and is not null.
401x-api-key is missing or invalid.
401Not entitled to the supplied custodial wallet.
401The Bakkt user could not be resolved from the supplied session.
409The custodial wallet is already linked to a different user.

On any of these, no user is created and no wallet is linked.

Sending messages as a Bakkt user

/initiate connects the user once. Messaging endpoints (/ask, /ask/stream) authenticate the user on every request, so Bakkt credentials must be sent each time — not just at initiation.

As at /initiate, x-bakkt-api-key is required from every caller, including users who onboarded through Zaira from scratch. A request without it is rejected with 400 and Missing "x-bakkt-api-key" header.

User typeHeaders on every /ask request
Custodialx-api-key + x-user-uuid + x-bakkt-api-key
Self-custodyx-api-key + x-bakkt-api-key + x-bakkt-session-id

Self-custody users must supply x-bakkt-session-id on every request. Because that session already identifies the user, x-user-uuid is optional for them — Zaira resolves the user from the session rather than from the UUID. You may still send it, which keeps the request shape consistent across user types.

For everyone else x-user-uuid is required: with no session to resolve the user from, it is the only identifier Zaira has.

Zaira has no wallet to sign with for self-custody users, so without a live session it has no way to act on their behalf and the request fails:

{
  "error": true,
  "message": "Unauthorized: self-custody user must authenticate through Bakkt Session ID",
  "errorCode": 401
}

Custodial users do not send a session ID. Zaira signs in with the wallet stored at /initiate and establishes the session itself.

What each user type can do

Custody determines which operations Zaira can carry out. This is resolved internally and is not exposed in any response.

CapabilityCustodialSelf-custody
Balances, transaction historyYesYes
Exchange rates, feesYesYes
Wallet fundingYesYes, only if ip_address was stored at /initiate
Create and manage beneficiariesYesYes
Execute a transferYesNo — Zaira prepares the beneficiary and payout details, the user signs and sends it themselves

Wallet funding means adding money to the wallet (for example linking a bank account or starting an ACH pull). It is not the same as executing a transfer to a beneficiary.

Endpoint requirements

EndpointAPI keyUser identityBakkt API key
POST /initiateRequiredNot requiredRequired
POST /askRequiredRequired, unless x-bakkt-session-id is sentRequired
POST /ask/streamRequiredRequired, unless x-bakkt-session-id is sentRequired
POST /check-executionRequiredRequiredNot required
GET /sessionsRequiredRequiredNot required
GET /infoRequiredNot requiredNot required
/webhooksRequiredNot requiredNot required
GET /healthNot requiredNot requiredNot required

The /initiate endpoint returns a user_uuid that you must use for all subsequent requests.


Did this page help you?