Stable Pro API · v1
Authentication and permissions
Keys, environments, permissions, rate limits.
Keys
Every request carries a key in the Authorization header:
Authorization: Bearer sp_live_7Kq2…
A key is sp_live_ (production) or sp_test_ (staging) followed by 40 letters and digits. The stable comes from the key: you never pass a stable id, and a key reads one stable only.
Keys are created by the owner of the stable in Stable Pro, Settings → Connections. A connection is your software; it can have more than one key over time. The owner sees each key's last four characters, its last use and the number of requests, and can revoke it at any time.
- A key is shown once, when it is created. Stable Pro keeps only a fingerprint: if it is lost, the owner creates a new one.
- Rotation: when the owner creates a new key for the connection, the previous one keeps working for 7 days, then stops. Replace it in your software within that window.
- Expiry: the owner may give a key an expiry date (90 days, one year, or none).
- A
sp_test_key is refused in production, and asp_live_key on staging (401,reason: wrong_environment).
When a key is not valid the answer is 401 with WWW-Authenticate: Bearer and a reason: missing, malformed, wrong_environment, unknown, connection_revoked, revoked, expired, rotated.
GET /connection returns the connection of the calling key: its name, its permissions, and the key itself (never the secret).
Permissions
The owner chooses what the connection can read:
| Permission | Opens |
|---|---|
charges:read | charges and adjustments, customers' balance |
payments:read | payments, allocations, credit entries |
receipts:read | Stable Pro receipts and their PDF |
customers:read | customers: code, kind, name, whether still active |
customers.fiscal:read | customers' invoice details: structured address, tax identifiers, tax code; and the tax data of who paid on behalf of a customer |
A request without the permission of its endpoint answers 403 with type: …/forbidden and missing_permission. Without customers.fiscal:read the invoice details are absent from the response, not null: they are not there at all, nested objects included. Every read of invoice details is counted separately in the stable's request log.
/connection, /organization, /codes and /events need no specific permission. Each event is shown only with the permission of the object it points to (see Events).
The Accounting area
The API is part of the Accounting area of the stable's plan. If the stable does not have it, every request answers 403 with type: …/accounting-disabled.
Rate limits
| Limit | Value | When exceeded |
|---|---|---|
| per key | 60 requests per minute | 429, Retry-After: 60 |
| per stable | 10,000 requests per day | 429, Retry-After: 86400 |
If the limiter itself is unavailable the API answers 503 with Retry-After: 30: it never lets requests through unchecked.
Read only
Version 1 reads. It cannot create, change or delete anything in Stable Pro. Writing back the documents your software issues (number, status, which facts they cover) is the next phase of the API.