Skip to content

Authentication ​

The recommended 2026-10 API uses business-level API clients and Bearer credentials.

http
Authorization: Bearer rvi_live_xxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create 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 ​

ScopeWhat it allows
stores:readList the stores the client is authorized for, and read a single store.
orders:readRead orders and order detail.
orders:writeCreate orders, update order status, and attach products to an order.
products:readRead products and product detail.
products:writeCreate and update products.
reviews:readRead reviews and product reviews.
statistics:readRead shop and product statistics.
invitation_suppressions:readRead the invitation suppression list; also requires personal_data:read because entries contain email addresses.
invitation_suppressions:writeAdd and remove invitation suppressions.
personal_data:readReceive 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}/....

ScopeWhat it allows
connections:readList the connections granted to the client for a store, and read a single connection.
order_statuses:readRead the order status catalog synchronized for a connection.
order_sources:writeReplace the order status catalog and report order source state transitions.
invitation_policies:readRead the effective invitation policy of a connection.
invitation_audit:readRead privacy-safe invitation policy audit events and per-order eligibility events.
invitation_backfills:writeRequest 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:

  1. The Bearer credential must be valid — otherwise 401 with invalid_token.
  2. The client must hold the required scope — otherwise 403 with insufficient_scope.
  3. The client must hold a grant for that connection, and the connection must be active and belong to the store in the path — otherwise 404 with connection_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.

http
X-API-KEY: revi_test_xxxxxxxxx

The 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:

json
{
  "success": false,
  "error": {
    "code": "authentication_required",
    "message": "API key not provided. Include your API key in the X-API-KEY header."
  }
}

Invalid key:

json
{
  "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:

http
Revi-Version: 2026-10
X-Request-ID: 2d87f617cd344da5ae5240cf3c049379

Each 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 401 and 403 responses as hard failures and stop retry loops until configuration is fixed.

Public API documentation for Revi.