Apps
An app is the access one system has to one store: its scopes, the locations it works with and, if set, the addresses it may call from. Apps are created in Settings → API and webhooks by someone with the right to manage the API — by default the owner — and nobody can give an app more than they have themselves.
The app acts in the store as its own member. Orders it places and stock it changes are signed with its name, so the store sees in its history what the integration did.
The API is part of the plan. If the store moves to a plan without it, requests get 403 integration_api_not_in_plan until the store returns; apps and tokens stay as they were.
Scopes
A scope opens a resource for reading or for writing: catalog:read, orders:write. A write scope includes the read scope of its resource. The table of scopes shows which endpoints each one opens.
Two scopes add fields to the responses of another resource: costs:read adds cost prices to catalog variants and order items, and customers:read adds the contacts, address and comment of the customer to orders and the recipient to fiscal documents. Without the scope these fields are absent from the response, not empty.
A request without the scope of its endpoint gets 403 insufficient_scope. The response names the missing scope, and the store adds it to the app:
curl "https://api.saleya.app/v1/orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:read"
{
"type": "insufficient_scope",
"title": "Scope is missing",
"status": 403,
"detail": "This request needs the orders:read scope. The store owner grants it in the app access settings.",
"required_scope": "orders:read",
"accepted_scopes": [
"orders:read"
]
}Tokens
- A token starts with
saleya_at_. Its last six characters are a checksum: a token with a typo is rejected before it is looked up, and secret scanners recognize a leaked one. - The store keeps only a hash of the token and its first characters, so the token is shown once, when it is issued.
- An expiry date is optional. The store owner gets an email before a token expires.
- An app has at most 2 current tokens: one in use and one being rolled out.
To rotate a token, issue a new one that replaces the old and choose how long the old one keeps working. Deploy the new token within that time. Revoking takes effect with the next request; deleting an app revokes all its tokens.
type of 401 | Meaning |
|---|---|
api_token_missing | There is no Authorization: Bearer header. |
api_token_invalid | The format or the checksum is wrong, or there is no such token. |
api_token_expired | The expiry date has passed. |
api_token_revoked | The token was revoked, the app deleted or the store closed. |
Keep tokens safe
- Keep the token on your server. A token in a browser, a mobile app or a repository is a leaked token.
- Limit the app to the addresses of your servers: a request from any other address gets 403
ip_not_allowed. - The store owner gets an email when a token is issued or revoked and when the access of an app changes.
- The request log of the app in the store admin keeps every request for 30 days: method, path, status and the
typeof an error, without bodies. - If a token leaks, revoke it at once: revoking does not wait for a replacement.