Authentication

Every request carries one header, x-api-key, and the key in it is the whole credential.

curl https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/balance \
  -H "x-api-key: avvio_live_…"

A key is avvio_live_ or avvio_test_, a 32-character lowercase hex public id, _, and a 43-character base64url secret. Copy the whole value. The prefix is part of the credential, so an avvio_test_ key cannot move real money. There is nothing to sign.

Treat the key like a database password

• Store it in a secrets vault, or in an environment variable if you have no vault.
• Never commit it, ship it in a client-side bundle or mobile app, or paste it into a screenshot or support ticket.
• Call the API from your server only, with test and live keys alike. The API reference’s Try It console is the one place to paste a test key.

A leaked key spends your balance

If a key is exposed, revoke it in the dashboard; revocation is immediate. Then issue a successor and tell us at [email protected]. To replace a healthy key without downtime, rotate it instead: the successor is live before the predecessor stops.

Getting a key

Issue keys in the dashboard. A key is shown once. We store only a hash and cannot show it again, so copy it when it appears.

In the API reference, paste the complete avvio_test_* value as the API key and use Try It on any operation. Put your normal organization id in orgId; the test key routes the request to your sandbox. Never paste a live key there.

These settings, chosen at issue and enforced on every request, limit what a leaked copy can do:

Setting	What it buys
Read-only (the read scope)	The key can reconcile but cannot spend
Crypto payouts (the crypto_payouts scope)	The key may pay crypto recipients in USDC from your organization’s own wallet. Off unless you grant it, and only alongside write. A key without it gets CRYPTO_PAYOUTS_DISABLED
Refunds (the refunds scope)	The key may refund checkout payments to buyers. Off unless granted, only alongside write, and only an owner or admin can grant it. A key without it gets INSUFFICIENT_SCOPE on the refund route
IP pinning (allowlisted source addresses)	Requests from any other address are refused
Expiry	One year by default, two at most

Security covers what each setting enforces and what rotation carries forward.

Give a read-only key to anything that only observes, such as a reconciliation job, a monitoring probe or a dashboard. Keys spread most in those places.

One key per environment

A test key addresses the same organization id as your live key and resolves, server-side, to that organization’s sandbox. Staging and production differ by one variable.

Issue a separate key per service too, so you can revoke one without taking down the others.

Expiry, rotation, and pinning

The dashboard shows each key’s expiry from the day it is issued.

Rotating a key (the dashboard’s Rotate, which calls POST /organizations/{orgId}/api-keys/{apiKeyId}/rotate from a signed-in session; an API key cannot call it) issues a successor and gives the predecessor a deadline, 24 hours by default. Deploy the new key, confirm traffic has moved, and let the old one lapse.

Pin keys to source addresses where you can. A payout service usually runs from a few known egress addresses, and a pinned key is useless outside your network.

Retries

Every money-moving request takes an Idempotency-Key. The same key with the same body replays the stored response instead of paying twice. See Idempotency.

Errors

type	Meaning
UNAUTHORIZED	Missing, malformed, unknown or revoked key
KEY_EXPIRED	The key has expired. Issue a new one; an expired key cannot be rotated
KEY_IP_NOT_ALLOWED	This key is pinned, and this request came from elsewhere
FORBIDDEN	Valid key, wrong organization
INSUFFICIENT_SCOPE	A read-only key attempting to spend or to read full account details, or a key without the refunds consent attempting a refund
LIVE_KEY_ORG_NOT_APPROVED	A live key writing before your business verification is approved. Reads work
ACCOUNT_BLOCKED	Your organization is suspended. Contact us

An unknown, revoked or wrong key all get the same answer, because telling them apart would only help someone guessing. Errors lists every error type with whether your money moved and whether retrying is safe.

What a key cannot do

A key cannot accept provider terms, manage your team, issue further keys, approve or reject a held payout, or register, pause, re-sign or replay a webhook endpoint. Those stay human actions in the dashboard. A key may read the approval queue (GET .../payouts/approvals) and the audit trail (GET .../audit-events). The API reference lists every route a key may call.