Authentication
Every merchant endpoint is authenticated with a single header — X-Api-Key. Keys are scoped to one project, created in the dashboard, and meant for server-to-server calls only.
The header
Send your key as X-Api-Key on every merchant request. There is no OAuth flow, no token exchange, and no expiry to refresh.
curl https://api.suward.com/v1/payments \
-H "X-Api-Key: $SUWARD_API_KEY"A missing or invalid key returns 401 Unauthorized with the standard error body. → Errors & limits
What needs a key and what doesn't
| Surface | Key | Notes |
|---|---|---|
| Payments, Static Wallets, quotes, simulations | required | Merchant view — full payment and deposit objects. |
GET /v1/payments/{paymentId} without a key | optional | Returns the limited customer view — this is what the public payment page reads. → Get payment |
POST /v1/payments/{paymentId}/activate | public | Customer-facing: the checkout page activates the payment when the customer opens it. |
| Assets, blockchains | public | Reference data, no authentication. → Assets & networks |
Scope: one key, one project
A key belongs to a single project and can only see and act on that project's resources. Use separate projects — and therefore separate keys — for separate products or environments, and the blast radius of any one key stays inside its project.
Handling the key
- The key is shown once, at creation. Store it where you store other secrets; if it is lost, create a new one and revoke the old.
- Server-side only. Never ship a key to a browser, a mobile app, or anything a customer can read. The hosted checkout needs no key on the customer's side by design — no secrets touch the browser. → Hosted checkout
- Rotation and revocation are instant. Create the replacement, deploy it, then revoke the old key — requests with a revoked key start failing with
401immediately. - Keys carry limits. Rate limits are enforced per key; on
429, back off and retry. → Limits
Never put a key in a redirect or a webhook handler's reply
The return-to-store redirect is a plain browser navigation and its parameters are hints, not
proof. Confirm state with an authenticated GET /v1/payments/{paymentId}.
What a key can never do
API keys carry limits and are scoped to a single project; a leaked key is contained by instant revocation. What a key can never do: withdrawals are configured and approved in the dashboard under 2FA and role-based access, not over the API-key surface. → Auto-withdrawals
Verifying inbound traffic
Authentication protects calls you make to Suward. Calls Suward makes to you — webhooks — are authenticated the other way round: an Ed25519 signature over the raw body, verified against your project's webhookPublicKey. Never treat an unsigned request to your webhook endpoint as a payment event. → Verify, then trust
Something unclear? payments@suward.com — we treat every integration question as a documentation defect.