The two headers
Every authenticated request sends two headers:X-Tenant-Id selects which tenant you’re acting on. Many keys can have admin scope across multiple tenants, so the gateway needs both bits to route the request.
Key types
Three key prefixes distinguish purpose:| Prefix | Type | Where it lives |
|---|---|---|
algv_… | Tenant-scoped API key | Used by your backend for normal API calls |
algvc_… | Admin / control-plane key | Issued to operators only. Has scope to manage tenants. |
algvw_… | Webhook signing secret | Per-destination. Used by AlgoVoi to sign outbound webhooks; receivers use it to verify. |
Where to get a key
Sign in todash.algovoi.co.uk and go to Settings → API keys. New keys can be scoped per-environment (test or live) and per-purpose (read-only, payment-write, etc.).
Rotation
Rotation is a one-click operation in the dashboard:- Click Rotate on the key you want to replace.
- The dashboard issues a new key and shows it once.
- Both the old key and the new key are valid for 30 days.
- After 30 days the old key is revoked.
Webhook secret rotation
Webhook signing secrets rotate the same way. AlgoVoi will sign with the new secret immediately, but accept signatures from the old secret as valid for 30 days during the overlap window. Receivers can verify with both during the overlap.Test mode versus live mode
Each key is bound to a mode:- Test mode keys can only call testnet networks (Algorand testnet, Base Sepolia, Solana devnet, etc.).
- Live mode keys can call mainnet, but only after the tenant has passed KYC. See KYC and mainnet.
Scopes (admin keys)
Admin keys carry a scope list. Common scopes:tenants:adminapikeys:adminkyb:writelive:activatepayments:readaudit:read
algv_… key covers the entire normal payment surface.
See also
- API introduction for base URL and content type
- Errors for what 401 and 403 responses look like