REST API Tokens

Scoped tokens for the SIBI REST APIs.

The SIBI REST APIs authenticate with REST API tokens. Create one in the SIBI Developer Portal, choose the scopes it should carry, and send it as a bearer token:

Authorization: Bearer YOUR_REST_API_TOKEN

REST API tokens are separate from the GraphQL tokens described in Authentication. The two are not interchangeable:

A REST API token works only on the REST APIs. The GraphQL API rejects it.
A GraphQL token still works on some REST endpoints, but that support is limited and going away. See GraphQL tokens on REST.

Scoped Permissions

Every REST API token has scopes. The scopes you pick at creation time limit what the token may do. An endpoint whose scope the token does not have will refuses the request with an error message indicating what scope is nessary to complete the request.

Grant the narrowest set your integration needs. A token that only reads the product catalog should carry read:products and nothing else, so a leaked token cannot place or cancel orders.

Scopes cannot be added to an existing token. To widen or narrow an integration’s access, create a new token with the scopes you want and revoke the old one.

Available scopes

Scope	Grants
`*`	Full access: every scope in the catalog, including ones added later
`read:*`	Read access to everything in the catalog, including scopes added later
`cancel:orders`	Request cancellation of existing orders
`create:orders`	Create orders
`read:assets`	Read the assets installed at your properties
`read:field-bins`	Read the bins and stock levels at your field locations
`read:field-issuances`	Read the issuance history of your field locations
`read:field-locations`	Read your field inventory locations (service trucks)
`read:invoices`	Read invoices
`read:offers`	Read offers
`read:orders`	Read orders
`read:own:orders`	Read only the orders your user placed
`read:product-categories`	Read the product category catalog
`read:products`	Read the product catalog
`test:permission`	Reserved for verifying that scope enforcement works end to end
`write:offers`	Create and modify offers

* and read:* are wildcards: a token carrying one is granted the matching scopes, including scopes added to the catalog after the token was issued. Prefer naming the scopes you use.

Production and test tokens are distinct

A token is created for one environment and rejected by the other. A production token is refused by the test environment at https://dev.sibi.pro with 403 TOKEN_ENVIRONMENT_MISMATCH, and a test token is refused the same way by https://api.sibipro.com. Create a token per environment.

See Test REST Environment for what the test environment does and does not do.

Scope refusals

Status	Code	Meaning
401	`UNAUTHORIZED`	No `Authorization` header, or a token we cannot resolve
403	`INSUFFICIENT_SCOPE`	Valid REST token, but it does not carry a scope this endpoint accepts
403	`REST_TOKEN_REQUIRED`	A GraphQL token was sent to an endpoint that requires a REST API token
403	`TOKEN_ENVIRONMENT_MISMATCH`	The token was created for the other environment

INSUFFICIENT_SCOPE means create a token with one more scope. REST_TOKEN_REQUIRED means create a REST API token instead of using a GraphQL token.

GraphQL tokens on REST

GraphQL tokens predate scopes, so the REST endpoints that shipped before scopes existed still accept them and apply no scope checks. That support is limited and deprecated:

Endpoints released after scopes shipped refuse GraphQL tokens outright with 403 REST_TOKEN_REQUIRED. Today that includes GET /products, GET /orders, and the HVAC matchup endpoints.
Endpoints that still accept them will stop. Treat every REST endpoint as requiring a REST API token.
New REST functionality is only reachable with a REST API token.

Migrate now: create a REST API token with the scopes your integration uses, swap it in, and revoke the GraphQL token once nothing depends on it.

Revoking a token

Revoke a token from the SIBI Developer Portal, or have the token revoke itself:

curl -X DELETE https://api.sibipro.com/token \
  -H "Authorization: Bearer YOUR_REST_API_TOKEN"

A successful revocation returns 204 No Content. The token authenticates nothing afterwards.