Authentication

Settlra uses API key authentication. Every request must include your API key in theAuthorization header as a Bearer token.

API key format

Sending the authorization header

Include your API key as a Bearer token in the Authorization HTTP header.

"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/payouts \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key_here" \
  "color:#79c0ff">-H "Content-Type: application/json"

"color:#8b949e">// Set once, reuse across all requests
"color:#ff7b72">const headers = {
  'Authorization': `Bearer ${process.env.SETTLRA_API_KEY}`,
  'Content-Type': 'application/json',
};

"color:#ff7b72">const response = "color:#ff7b72">await fetch('https://api-sandbox.settlra.com/v1/payouts', {
  headers,
});

Managing your API keys

Create, rotate, and revoke API keys in the Dashboard → Settings → API Keys. You can have multiple keys active at once — useful for rotating keys without downtime.

Idempotency

All write endpoints (POST) accept an idempotency_key field in the request body. If you retry a request with the same idempotency key within 24 hours, the API returns the original response instead of creating a duplicate — even if the original request timed out.

Best practice: use a UUID or a deterministic hash of your internal record ID as the idempotency key.

"color:#ff7b72">import { randomUUID } "color:#ff7b72">from 'crypto';

"color:#8b949e">// Use a stable ID "color:#ff7b72">from your system (e.g. your DB primary key)
"color:#ff7b72">const idempotencyKey = `payout-${myPaymentRecord.id}`;

"color:#8b949e">// Or generate a UUID "color:#ff7b72">for one-off requests
"color:#ff7b72">const idempotencyKey = randomUUID();

Rate limits

Requests are rate-limited per API key. Exceeding the limit returns HTTP 429 Too Many Requests.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1719835260

Security best practices

• Never commit API keys to version control. Use environment variables or a secrets manager.
• Use the sandbox (sk_sandbox_) for all development and testing — it uses fake money.
• Rotate keys regularly and immediately if you suspect a key has been exposed.
• Restrict key permissions using dashboard scopes if you only need read-only access in some services.
• Verify webhook signatures on all incoming webhooks — see the Webhooks reference for details.

Error responses

Authentication failures return HTTP 401 or 403:

// 401 — Missing or invalid API key
{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
}

// 403 — Valid key but account issue
{
  "error": "KYC_REQUIRED",
  "message": "Account KYC status is PENDING. Contact support to complete verification."
}

// 403 — Account suspended
{
  "error": "FORBIDDEN",
  "message": "Account is suspended"
}