Moja SwitchDocs Sandbox live

Guide

Authentication

API keys, environments, scopes, request IDs and rate limits.

Every request to a /v1 path carries an API key as a Bearer token. The only exception is POST /signup, which creates your first sandbox key.

http
GET /v1/payments/pay_abc123def456 HTTP/1.1
Host: api-sandbox.mojaswitch.com
Authorization: Bearer sk_sandbox_<64 hex characters>

Keys and environments

Prefix Environment How you get it
sk_sandbox_ Sandbox POST /signup, or issued by Moja Switch
sk_live_ Production Issued by Moja Switch at go-live only
  • A key is bound to one environment when it is issued, and its prefix tells you which.
  • A key is shown once. Moja Switch stores only a SHA-256 hash of it, so a lost key cannot be recovered, only replaced.
  • To identify a key to us, send its display prefix (sk_sandbox_ plus the first six hex characters). Never send the full key.

Handling keys safely

  • Keep keys in a secrets manager. Never put one in a URL, a log line, client-side or mobile code, a screenshot or a support ticket.
  • Call the API from your servers only. A key in a browser or an app is a leaked key.
  • If you suspect a key is exposed, tell Moja Switch immediately so it can be revoked.

What is checked, in order

  1. The key is present and active. Otherwise 401 unauthorized. A 401 never says whether the key was malformed or unknown.
  2. Your partner account is enabled. A suspended account gets 403 forbidden on every route.
  3. On POST /payments, POST /quotes and GET /fx/reference, you are entitled to the corridor you name. Otherwise 403 corridor_not_entitled (or 503 entitlement_unavailable if the check itself could not run; nothing is forwarded either way).
  4. Your key carries the scope the route requires. Otherwise 403 insufficient_scope.

Scopes

Scopes are deny-by-default. Each operation in the API reference names the scope it needs.

Scope Grants
read Read payments, receipts, payouts, corridors, the FX reference rate and account readiness
write Create quotes and payments; sandbox-only actions
cancel Cancel a payment
end_users:read / end_users:write Read, or create and change, end users
verifications:write Start and read identity verifications
recipients:read / recipients:write Read, or manage, an end user's saved recipients

The end_users:*, verifications:* and recipients:* scopes are not granted implicitly to keys issued before they existed. Ask for the narrowest set you need.

Request IDs and correlation

  • Every error carries error.request_id (req_…), also returned as the X-Request-Id header. Quote it to support.
  • You may send X-Correlation-Id to trace a request across our services. If you do not, one is generated. It is echoed on the response.

Rate limits

  • Limits apply per partner per environment, not per key or IP address.
  • Responses on limited routes carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (and the same values as X-RateLimit-*).
  • Over the limit you get 429 rate_limit_exceeded with a Retry-After header in seconds. Wait at least that long.
  • Production limits are not published yet. Read the headers; do not hardcode a number.

OAuth2 Planned

OAuth2 client credentials are planned. Only API keys are accepted today.