API reference¶
TL;DR - Magma's REST API is the same surface the dashboard uses. Base URL is https://app.magma.builders/api. Auth is either a long-lived API key (sent in the X-Api-Key header) or a Keycloak OAuth 2.0 bearer token. The full machine-readable spec lives at /api/docs/swagger.json - that is the source of truth; this page is the orientation.
When to use the API¶
The dashboard covers everything operators need day-to-day. Reach for the API when you want to:
- Mirror the customer list or balances inside your own back-office.
- Trigger top-up reminders or crypto-payment links from your own customer portal.
- Pipe transactions into your accounting / data warehouse.
- Build webhook handlers that wait for
completed/failedstatus changes.
If the dashboard already does what you need, use it - there's no separate API access fee, but a programmatic integration is a code surface to maintain.
Base URL¶
All endpoints below are versioned under /v1.
Authentication¶
Magma supports two ways to authenticate API calls:
Option A - API key (recommended for integrations)¶
Operators with admin or operate roles can mint long-lived API keys directly from the dashboard. View users can't see the section.
- Click your profile avatar at the bottom-left of the dashboard.
- On the Account Details tab, scroll to the API Keys card.
- Click New API Key, give it a name (e.g.
CI/CD Pipeline) and an optional expiration date - leave the date blank for a key that never expires. - Copy the generated key immediately. It is shown once and only once - store it in your secrets manager before closing the modal.
The card lists every existing key with its name, key prefix, status, expiry date, creation date, and last-used timestamp. Revoke any key from the actions column to invalidate it instantly.
Send the key in the X-Api-Key header on every request:
Option B - Keycloak bearer token (user-acting integration)¶
When you want the API call to act as a specific operator (e.g. an internal tool that surfaces dashboard data to that operator):
- Obtain a bearer token from your Keycloak realm - the same realm operators log in through. Use the standard OAuth 2.0 auth-code flow.
- Send the token as
Authorization: Bearer <token>on every request.
Roles and permissions¶
Whichever path you use, the underlying operator's role (admin / operate / view) determines what the call can do. Endpoints enforce role permissions exactly as the dashboard does.
Managing keys via API¶
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/api-keys |
List your keys (metadata only - never the secret). |
| POST | /v1/api-keys |
Mint a new key. Body: name, optional expires_at (ISO 8601). |
| DELETE | /v1/api-keys/{id} |
Revoke a key. |
Required headers¶
Two headers are flow-specific:
| Header | When | Notes |
|---|---|---|
Idempotency-Key |
POST /v1/payouts/fiat |
UUID. Replaying the same key returns the original result instead of double-charging. |
X-OTP-Code |
POST /v1/payouts/fiat |
6-digit TOTP code requested via POST /v1/payouts/fiat/send-otp immediately before. |
Endpoint cheatsheet¶
Endpoints are grouped to match this wiki's flows.
Operators¶
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/operators/invite |
Invite a new operator. |
| GET | /v1/operators |
List your team. |
| PUT | /v1/operators/{id} |
Disable / re-enable. |
See Invite operators and Manage your team.
Customers (organizations)¶
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/organizations |
Create a customer + trigger KYC link. |
| GET | /v1/organizations |
List with filters and KPI aggregates. |
| GET | /v1/organizations/{id} |
Single customer detail. |
| GET | /v1/organizations/{id}/dashboard |
Balance, VA, recent txns, KPIs. |
| PUT | /v1/organizations/{id}/fees |
Update markup overrides. |
See Create a customer.
Recipients¶
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/organizations/{orgId}/recipients |
Recipients on a customer. |
| POST | /v1/organizations/{orgId}/recipients |
Add a recipient to a customer. |
| GET | /v1/recipients/{id} |
Single recipient detail. |
| DELETE | /v1/recipients/{id} |
Delete recipient. |
See Recipients overview.
Virtual accounts (fiat)¶
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/organizations/{orgId}/virtual-accounts |
List a customer's fiat VAs. |
| GET | /v1/virtual-accounts/{id} |
Fiat VA details. |
| GET | /v1/virtual-accounts/{id}/balance |
Available + reserved. |
| GET | /v1/virtual-accounts/{id}/deposit-info |
Bank coordinates for top-up. |
| GET | /v1/virtual-accounts/{id}/bank-letter |
Provider-issued PDF (base64). |
See Virtual accounts.
Saved wallets / on-ramp (crypto VAs)¶
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/organizations/{orgId}/wallets |
Register a destination wallet on a customer. Provisions the paired crypto VA. |
| GET | /v1/organizations/{orgId}/wallets |
List a customer's saved wallets (each with its paired crypto VA + deposit coordinates). |
| GET | /v1/wallets/{id} |
Single saved wallet with the paired crypto VA, banking deposit coordinates, and status. |
| DELETE | /v1/wallets/{id} |
Disabled in v1 - upstream provider does not expose a VA deactivation endpoint. Contact support to retire a wallet. |
| GET | /v1/crypto/networks |
List supported networks and tokens (also used by crypto-to-fiat payouts). |
POST .../wallets body: label, address, network, token. Response
includes a virtual_account object: id, kira_va_id, mode (always
crypto), currency (always USD in v1), status (pending / active /
suspended), deposit_coordinates (populated only when status is
active).
See On-ramp.
Fiat payouts¶
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/payouts/preview |
Preview fees without executing. |
| POST | /v1/payouts/fiat/send-otp |
Trigger 6-digit OTP delivery. |
| POST | /v1/payouts/fiat |
Execute the payout. Requires Idempotency-Key and X-OTP-Code. |
See Fiat payouts.
Crypto-to-fiat payouts¶
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/payouts/crypto |
Generate single-use deposit address. |
| POST | /v1/payouts/crypto/upload-doc |
Upload supporting documents. |
| GET | /v1/crypto/networks |
List supported networks / tokens. |
Transactions¶
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/transactions |
Cross-customer list with filters. |
| GET | /v1/organizations/{orgId}/transactions |
Customer-scoped list. |
| GET | /v1/transactions/{id} |
Single transaction detail. |
| GET | /v1/transactions/{id}/receipt |
Per-transaction PDF receipt. |
| GET | /v1/transactions/export-csv |
Bulk CSV download. |
| POST | /v1/transactions/export-pdf |
Bulk PDF report. |
Status enums (quick reference)¶
- Operator status:
invited,active,disabled. - Customer status:
created,verifying,verified,active,rejected,review,suspended. - Transaction status:
created,pending,processing,completed,failed,action_required,under_review,returned,expired,canceled. - Transaction type:
deposit_fiat,deposit_crypto,payout_fiat,payout_crypto,crypto_conversion,fee. - Account type (fiat):
ACH,WIRE,SWIFT. - Virtual account mode:
fiat,crypto. - Virtual account status:
pending,active,suspended. - Networks (crypto-to-fiat payouts):
tron,polygon,solana,ethereum,arbitrum,base. - Networks (on-ramp):
polygon,solana,tron. - Tokens:
USDC,USDT(on-ramp combinations: Polygon + USDC/USDT, Solana + USDC/USDT, Tron + USDT).
The full enum definitions and edge cases live in the Swagger - when in doubt, that's the contract.
Stability¶
Endpoints under /v1 are stable. Breaking changes will land under /v2
with announcement and a deprecation window on /v1 before removal.