Authentication
The recommended 2026-10 API uses business-level API clients and Bearer credentials.
Authorization: Bearer rvi_live_xxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCreate the client in Developers → API clients, select its stores and scopes, and copy the credential when it is shown. The complete secret is displayed only once.
Bearer credentials are server-side secrets. They are not accepted by /api/2026-04, and legacy X-API-KEY credentials are not accepted by /api/2026-10.
Scopes and stores
Every operation requires a resource scope such as orders:read or products:write. Store resources always use /stores/{store_id}/...; an unauthorized and a nonexistent store both return 404.
personal_data:read is an advanced scope. Without it, customer names and email addresses are omitted from responses.
A credential that is missing the scope an operation requires receives 403 with the error code insufficient_scope.
Scopes available in 2026-10
| Scope | What it allows |
|---|---|
stores:read | List the stores the client is authorized for, and read a single store. |
orders:read | Read orders and order detail. |
orders:write | Create orders, update order status, and attach products to an order. |
products:read | Read products and product detail. |
products:write | Create and update products. |
reviews:read | Read reviews and product reviews. |
statistics:read | Read shop and product statistics. |
invitation_suppressions:read | Read the invitation suppression list; also requires personal_data:read because entries contain email addresses. |
invitation_suppressions:write | Add and remove invitation suppressions. |
personal_data:read | Receive customer names and email addresses instead of omitted fields. |
Connection-scoped scopes
These scopes apply to connection-scoped resources under /stores/{store_id}/connections/{connection_id}/....
| Scope | What it allows |
|---|---|
connections:read | List the connections granted to the client for a store, and read a single connection. |
order_statuses:read | Read the order status catalog synchronized for a connection. |
order_sources:write | Replace the order status catalog and report order source state transitions. |
invitation_policies:read | Read the effective invitation policy of a connection. |
invitation_audit:read | Read privacy-safe invitation policy audit events and per-order eligibility events. |
invitation_backfills:write | Request a refresh_state_only backfill and read its progress. |
None of these scopes can change invitation policy. Policy is configured only by the merchant in the Revi panel; the API exposes it read-only.
Existing credentials never receive the connection-scoped scopes automatically. Request each scope your integration needs explicitly.
Connection grants
A store can have several connections — each one is a separate integration linked to that store. An API client also needs an explicit connection grant for every connection it operates on, on top of its scopes and store selection.
The grant exists because order source state and invitation eligibility belong to one specific connection, not to the store as a whole. Scopes describe what an operation may do; the connection grant describes which connection it may do it to. Without that separation, a client authorized for one integration could rewrite the status catalog of another integration on the same store.
Grants are issued by Revi per client and per connection. They are not derived from the store selection and are not granted automatically when a scope is added.
Every connection-scoped request is therefore checked three times:
- The Bearer credential must be valid — otherwise
401withinvalid_token. - The client must hold the required scope — otherwise
403withinsufficient_scope. - The client must hold a grant for that connection, and the connection must be active and belong to the store in the path — otherwise
404withconnection_not_found.
The third check returns the same 404 whether the connection does not exist, is inactive, belongs to another store, or is simply not granted. This is deliberate: it prevents probing for connections the client is not authorized to see. Treat connection_not_found as a configuration problem and stop retrying until the grant is confirmed.
2026-04 compatibility authentication
The 2026-04 API continues to use API key authentication.
X-API-KEY: revi_test_xxxxxxxxxThe key identifies the integration account and resolves the associated business and store context. All documented /api/2026-04 endpoints require this header.
API Key Header
Every authenticated request requires X-API-KEY.
Missing key:
{
"success": false,
"error": {
"code": "authentication_required",
"message": "API key not provided. Include your API key in the X-API-KEY header."
}
}Invalid key:
{
"success": false,
"error": {
"code": "invalid_api_key",
"message": "The provided API key is invalid or has been deactivated."
}
}Store Context
Use the business and store context resolved by the API key unless an endpoint explicitly documents a store parameter.
If the API key is tied to a specific store, list and detail endpoints are scoped to that store automatically. If the key is business-wide, endpoints can return data across stores; endpoints that document id_store can be filtered explicitly.
Response Headers
Successful 2026-10 responses include:
Revi-Version: 2026-10
X-Request-ID: 2d87f617cd344da5ae5240cf3c049379Each version reports its own value, so 2026-10 responses keep Revi-Version: 2026-10 and 2026-04 responses keep Revi-Version: 2026-04.
Security Rules
- Never expose API keys or Bearer credentials in browser JavaScript.
- Store keys server-side in your application configuration.
- Rotate a key if it appears in logs, screenshots, or client-side code.
- Treat
401and403responses as hard failures and stop retry loops until configuration is fixed.