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	Stripe 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/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

Today: contact [email protected] to provision your merchant account and receive your first test key.

Soon: self-serve key creation from the business dashboard. The dashboard will show your prefix tail and let you copy the full key once, at the moment of creation. After that, only the prefix is visible — the secret tail is not recoverable.

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