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
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/api-keys | List keys with environment, status and last-used metadata. | apikeys:read |
| POST | /merchants/:merchantId/api-keys | Create a key. The secret is returned once, at creation. | apikeys:write |
| POST | /merchants/:merchantId/api-keys/:apiKeyId/revoke | Revoke a key immediately. | apikeys:write |
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | A label such as production-server. |
| environment | test | live | Yes | — |
| expiresAt | ISO date | No | Optional 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
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.