API REFERENCE

API keys

Merchant API keys authenticate server-to-server integration routes. They are not user sessions and they never carry the permissions of a person.

Manage keys

MethodPathPurposePermission
GET/merchants/:merchantId/api-keysList keys with environment, status and last-used metadata.apikeys:read
POST/merchants/:merchantId/api-keysCreate a key. The secret is returned once, at creation.apikeys:write
POST/merchants/:merchantId/api-keys/:apiKeyId/revokeRevoke a key immediately.apikeys:write
FieldTypeRequiredNotes
namestringYesA label such as production-server.
environmenttest | liveYes—
expiresAtISO dateNoOptional expiry. Expired keys are rejected by the guard.

Use a key

Integration routes accept Authorization: Bearer <secret-api-key>. The guard validates the key hash, merchant status and expiry before the request reaches the controller.

List products with a key

bashExample
curl "$SOBTRA_API_URL/api/v1/products?environment=test" \
  -H "Authorization: Bearer $SOBTRA_SECRET_KEY"

Where keys work

API-key routes are the integration surface: products, invoices, usage meters and usage events under /api/v1. Everything a signed-in person does, such as team management, roles or analytics, uses the session token instead.

Webhook endpoints

Incoming provider callbacks are posted to POST /webhooks/:merchantId/:provider/:environment with the provider's own signature header. They are not authenticated with a merchant API key; the signature is the authentication.