API keys

Every request to Soxara is authenticated with a merchant API key sent in the Authorization header:

Authorization: Bearer sxm_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789ABCD

There’s no other auth model. No OAuth flows for your server-to-server calls, no signed requests, no SOAP. Just a bearer key, same as Stripe.

Anatomy of a key

sxm_live_AbCdEfGh   IjKlMnOpQrStUvWxYz0123456789ABCD
^^^      ^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
│        │          └── secret tail (32 chars). Treat like a password.
│        └── prefix tail (8 chars). Searchable, identifies the key.
└── always "sxm_"

sxm_ is the constant Soxara prefix (think Stripe’s sk_).
live or test immediately follows — this is what tells our gateway which environment to route to.
The 8-char prefix tail is what you’ll see in dashboards and logs. It’s safe to share for support purposes (“hi, the key starting with sxm_live_AbCdEfGh is failing”).
The 32-char secret tail is the actual credential. Soxara stores only a bcrypt hash of this on our side — we cannot recover or display a key after it’s first created.

Test vs live

Prefix	Environment	What it touches
`sxm_test_`	Sandbox	Card test mode, MoMo sandbox, fake wallets — no real money
`sxm_live_`	Production	Real cards, real MoMo, real money. Treat with appropriate care.

A single merchant account can mint both. You’ll typically use sxm_test_* for development and CI, sxm_live_* only in production. See Environments for the routing detail.

Authenticating a request

Bearer auth on every call:

curl https://api.soxara.com/v1/api/payments \
  -H "Authorization: Bearer $SOXARA_KEY"

If the header is missing, malformed, or the key is revoked, you get:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or malformed merchant API key."
  }
}

HTTP status 401.

Creating keys

Self-serve, from the business dashboard: Settings → Developers → New API key. Name the key, choose live or test, and pick its scopes — no waiting on us, no partners@ email required.

The dashboard shows your prefix tail immediately and lets you copy the full key once, at the moment of creation. After that, only the prefix is visible — the secret tail is not recoverable, so copy it somewhere safe (a secrets manager, an env var) before you close the dialog.

If you need a merchant account provisioned in the first place (you don’t have a Soxara business account yet), that’s still [email protected] — key creation itself is self-serve once you’re in.

Storing keys

Never commit a key to source control. Use environment variables, a secrets manager, or your platform’s equivalent.
Separate test and live keys in your config. Don’t fall back from one to the other automatically — that’s how live charges end up in test runs.
Don’t ship a key in a frontend bundle, mobile app, or anywhere a customer can extract it. API keys go on your server. Customer-facing components use Soxara’s hosted payment surfaces or per-session tokens; talk to us if you need a pattern for a specific use case.

Logging keys

In your application logs, log only the prefix tail (sxm_live_AbCdEfGh), never the full key. The prefix is identifying without being a credential. Our own logs follow the same rule.

If you ever accidentally log a full key — committed code, screenshot, support ticket — treat it as compromised and rotate immediately. See Rotating & revoking keys.

Idempotency Scopes