Authentication

Every request is authenticated with a workspace-scoped API key. This page covers the key's anatomy and storage, the scope catalog, what a key is told when its workspace may not use the API, network allow-lists, rotation, and the guarantees the platform makes in return.

The API key

Keys are issued from the merchant dashboard (Developers → API keys) and have three parts:

• a fixed prefix, xeg_live_, so keys are recognizable in logs and secret scanners;
• a public lookup segment, up to the dot;
• a secret segment after the dot, shown once at issuance.

Everything before the dot (xeg_live_AbCdEfGhIjKl below) is the key's public prefix, as the dashboard and GET /api/v1/me show it. Xegora authenticates a key by a keyed hash of it. For 15 minutes after issuance it also keeps an encrypted copy of the key, solely so that an exact retry of the same issuance (after a dropped connection, say) hands back the same key instead of issuing a second one. After those 15 minutes the copy is purged and only the hash remains: the secret can never be retrieved again — a retried issuance is refused (credential_replay_expired) — so store the key when you create it. A lost key cannot be recovered, only replaced.

Send the full plaintext key on every request:

X-Api-Key: xeg_live_AbCdEfGhIjKl.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

There is no cookie, session, or OAuth handshake on this surface — the header is the whole story.

How a request is refused

Each refusal has its own status and code, so your logs say which part of the setup to look at:

The checks run in that order: a workspace that may not use the API is told so before any scope is judged.

Access standing — api_access_inactive

A key belongs to its workspace, and the workspace's standing on the API travels with it. When the workspace may not use the API, every refused request is answered 403 with code: "api_access_inactive", a reason, and — when the subscription's paid-through instant is known — paidThroughUtc:

{
  "title": "The request could not be completed.",
  "status": 403,
  "detail": "Use the error code and correlation ID when contacting support.",
  "code": "api_access_inactive",
  "correlationId": "0198e001a2b37c4d8e9f0a1b2c3d4e5f",
  "reason": "subscription_overdue",
  "paidThroughUtc": "2026-10-01T00:00:00+00:00",
  "message": "The subscription isn't paid, so the API only reads what the workspace already has until the invoice is paid. Pay it in the dashboard."
}

The message is written for the reason, not for the code, so each of the four standings below says what to do about that standing — in the response language. Branch on reason, never on the sentence.

While the subscription is overdue or the entitlement has ended, the workspace keeps reading what it already has: every GET, POST /orders/{orderId}/fulfillment (the codes of orders you already bought), and POST /withdrawals/quotes. Everything that would change something is refused: POST /quotes, POST /orders, PUT /wallet/deposit-addresses, POST /withdrawals and POST /withdrawals/{withdrawalId}/cancellation. Settle the invoice in the dashboard and the same keys work again — nothing needs to be reissued. GET /api/v1/workspace shows the access status and paid-through instant at any time while reads are allowed.

Scopes — least privilege by design

Each key carries an explicit scope set chosen at issuance. Grant only what the integration needs:

Three scopes deserve special attention:

• orders.create spends money. A storefront that only displays the catalog should not hold it.
• Revealing codes hands over the goods. orders.read alone never reveals; reveal with a key that holds orders.reveal, or with the key that buys (orders.create). A support or reporting tool that reads orders should not hold either.
• wallet.withdraw moves money out. It is deliberately separate from wallet.read, so a leaked read-only or ordering key can never trigger a payout. Withdrawals also never name a destination — funds can only go to the payout destination your owners registered and Xegora approved, after a business-day hold, and are cancellable throughout it. See Withdrawals.

A practical split for most integrations:

GET /api/v1/me lists a key's scopes, expiry and how many address ranges it is restricted to — check it at deploy time rather than learning from a 403.

Network allow-lists and expiry

At issuance you can bind a key to:

• CIDR allow-list — the key is accepted only from these source addresses; from any other address the request is refused 403 ip_not_allowed, and no use of the key is recorded. Strongly recommended for production keys with money-moving scopes.
• Expiry — an absolute expiration instant. An expired key authenticates nothing (401).

Revocation from the dashboard is immediate (401 from then on).

Key hygiene

• Store keys in a secret manager, never in source control, mobile apps, or browser code. The Integration API is a server-to-server surface; calling it from a browser would expose the key.
• Rotate by issuing a new key, deploying it, then revoking the old one — both are valid during the overlap, so rotation needs no downtime.
• Scope one key per system, not one key for everything; a compromise then has a known blast radius.
• A key belongs to the workspace, not to the person who issued it: it keeps working when that person leaves the team or stops managing keys (the workspace's owners are told which keys that person issued). Review and revoke keys you no longer need.
• Watch for 401/403 spikes in your logs — they are the earliest sign of a revoked, expired, mis-scoped or address-restricted key, or of a workspace whose access lapsed.

Transport guarantees

• HTTPS only. The API is served exclusively over TLS at https://myapi.xegora.com.
• Workspace isolation. The workspace is derived from the key on every request. No endpoint takes a workspace id — a body that names one is refused as an unknown member — so cross-tenant access is structurally impossible. Another workspace's order, quote, deposit or withdrawal is 404, exactly like one that does not exist.
• Strict request bodies. A body member the contract does not have is refused (400 invalid_request, named in errors), never silently ignored — a misspelt maximumTotal cannot order without its ceiling.
• Rate limiting. 120 requests per minute per workspace (fixed window), with catalog images on a budget of their own (300 per minute), plus a per-address limit applied before a key is checked. Every admitted response says the budget and what is left of it (RateLimit-Limit, RateLimit-Remaining); excess requests receive 429 rate_limited with Retry-After — see Errors & Retries.
• No secrets in transit by default. Order bodies and webhooks never contain fulfillment artifacts; codes exist only in the response of an explicit, audited reveal call, always delivered Cache-Control: no-store.
• Auditability. Every mutating call is attributed to the exact API key that made it, and every response — successes and errors alike — returns its correlation id in the X-Correlation-Id header, which an error repeats in correlationId (send your own in X-Correlation-Id).