Scopes

Every API key is minted with a list of scopes that determine what it can do. Scopes are checked at the gateway before your request reaches the underlying service.

A request with a key that doesn’t carry the required scope returns:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This endpoint requires the 'payments:create' scope."
  }
}

HTTP 403.

Available scopes

Scope	Endpoints	Notes
`payments:create`	`POST /v1/payments`	Create PaymentIntents. The most common scope for checkout integrations.
`payments:read`	`GET /v1/payments/*`	Retrieve payments, list payments. Read-only.
`refunds:create`	`POST /v1/refunds`	Issue refunds. Sensitive — keep separate from your checkout key when possible.
`transfers:create`	`POST /v1/transfers`	Wallet-to-wallet sends. Required for platforms that move money between Soxara users on their users’ behalf.
`gift_cards:redeem`	`POST /v1/gift-cards/{id}/redeem`	Redeem a gift card at the point of sale. Typical scope for POS terminals.
`gift_cards:create`	`POST /v1/gift-cards`	Issue new gift cards. Sensitive — separate from redeem.
`bill_payments:create`	`POST /v1/bill-payments`	Initiate utility bill payments (LEC, LWSC, etc.).
`webhooks:manage`	`POST/PATCH/DELETE /v1/webhook-endpoints`	Configure webhook endpoints. Usually a separate “admin” key, not your checkout key.
`merchant:read`	`GET /v1/merchant`	Read your own merchant profile, scope-list, settlement schedule.

Picking scopes

Two rules:

Least privilege. A frontend checkout integration needs payments:create only. A back-office refund worker needs refunds:create and nothing else. A POS terminal needs gift_cards:redeem and that’s it.
One key per role. Don’t mint one master key with every scope and use it everywhere. If your POS gets compromised, the only blast radius is gift card redemption — not your entire payment surface.

Default scopes

A new key created from the business dashboard defaults to:

payments:create
payments:read

These are the minimum to handle a checkout flow. Add more scopes to the key, or mint a separate key, as your integration grows.

What scope a request needs

Every endpoint in the API Reference lists its required scope at the top of the page. A request without that scope fails fast at the gateway — your downstream services never see the call.

API keys Rotating & revoking keys