Authentication

The SOAMTAR API uses bearer API keys over HTTPS only. Every request needs an Authorization header.

Key types

SOAMTAR provides two key types for each environment (test and live):

Type	Prefix	Use	Safety
Public key	pk_...	Client-side integration (SOAMTAR.js, mobile SDKs).	Safe to expose publicly.
Secret key	sk_...	Server-side API requests (PHP, Python… SDKs).	SENSITIVE. Never expose it.

Authentication format

Every request your server sends to the SOAMTAR API must carry your secret key in the Authorization header.

Authorization: Bearer sk_(test|live)_<your-secret-key>

WARNING

Never use your public key (pk_...) for bearer authentication from your server. It is meant for JavaScript running in your customer's browser.

Environments (modes)

Prefix	Use
sk_test_	Sandbox. No real transaction. Responses contain livemode: false.
sk_live_	Production. Real transactions and real settlement. livemode: true.

Never mix them: test and live objects are isolated — a test key cannot see live objects and vice versa.

Scopes

Each key carries a subset of capabilities. Create least-privilege keys:

Scope	Permission
can_initiate_payment	POST /payments, POST /subscriptions, POST /payments/{id}/splits
can_read_transactions	GET /payments, GET /payments/{id}, GET /subscriptions, GET /disputes
can_refund	POST /refunds
can_payout	POST /payouts

A request without the required scope returns 403 scope_insufficient.

Rotation

Dashboard → Developers → API keys → Rotate.

• The old key stays valid for 24 hours after rotation so you can migrate.
• Any key can be revoked immediately.
• SOAMTAR logs every use: key, IP address, requested scope, timestamp.

IP allowlist (optional)

For a live key you can restrict the allowed IP addresses:

Dashboard → API keys → Edit → Allowed IPs: 41.x.x.x, 41.y.y.y/24

A request from an unlisted IP returns 401 invalid_api_key.

Request signing (optional)

On top of the Bearer key, you can sign each mutating request (POST, PUT, PATCH, DELETE) with your secret key. It proves the request was built by a holder of the secret and limits replays to a 5-minute window. GET requests are never checked.

Header	Value
Soamtar-Timestamp	Current Unix time in seconds
Soamtar-Signature	v1= + hex(HMAC-SHA256(secret_key, "<timestamp>.<METHOD>.<path>"))

• <METHOD> is upper case (POST).
• <path> is the request path without the leading slash and without the query string, e.g. v1/payments, v1/refunds.
• The timestamp must be within ±300 s of SOAMTAR's clock, otherwise the API answers 400 invalid_timestamp. A header that does not start with v1= gets 400 invalid_signature.

const crypto = require('crypto');
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', process.env.SOAMTAR_SECRET_KEY)
  .update(`${ts}.POST.v1/payments`).digest('hex');

headers['Soamtar-Timestamp'] = ts;
headers['Soamtar-Signature'] = `v1=${sig}`;

Signing is optional hardening: requests without the two headers are accepted, and today a mismatching signature is logged rather than refused. Enforcement can be switched on platform-wide (strict mode), in which case a wrong signature returns 401 invalid_signature, so make sure your signatures are valid before relying on them.

Every server SDK can sign for you:

SDK	Option
Node.js	require('@soamtar/sdk')(key, { signRequests: true })
PHP	new SoamtarClient($key, ['sign_requests' => true])
Python	SoamtarClient(key, sign_requests=True)
Ruby	Soamtar::Client.new(key, sign_requests: true)
Go	soamtar.NewClient(key, soamtar.WithSignRequests(true))
Java / .NET	signRequests constructor flag

See each SDK page for the exact constructor.

Authentication errors

Code	Cause
missing_credentials	No Authorization header
invalid_api_key	Unknown, revoked or expired key, or IP outside the allowlist
scope_insufficient	Valid key without the scope this route requires

Security

• Never in clear on the client: never expose a live secret key in a web page, a mobile app or a public git repository.
• Encrypted storage: keep your keys in a secret manager (Vault, AWS Secrets Manager, Doppler).
• Regular rotation: at least every 6 months.
• Hash only: SOAMTAR only stores a hash of your key. If you lose it, rotate it.