---
title: REST API Tokens
description: Scoped tokens for the SIBI REST APIs.
---

The SIBI REST APIs authenticate with **REST API tokens**. Create one in the
**[SIBI Developer Portal](https://developer.sibipro.com/)**, choose the scopes it should carry, and send it as a bearer
token:

```http
Authorization: Bearer YOUR_REST_API_TOKEN
```

REST API tokens are separate from the GraphQL tokens described in
[Authentication](/getting-started/authentication). The two are not interchangeable:

- A REST API token works **only** on the REST APIs. The GraphQL API rejects it.
- A GraphQL token works **only** on the GraphQL API. The REST APIs reject it. See
  [GraphQL tokens on REST](#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 |
| `cancel:projects` | Cancel projects |
| `create:asset-exports` | Request a file export of your assets |
| `create:draft-orders` | Create draft orders to preview an order’s options, pricing, and availability |
| `create:feedback` | Send feedback and questions about the Sibi Public API |
| `create:from-draft:orders` | Create an order from an existing draft order |
| `create:orders` | Create orders |
| `create:projects` | Create projects |
| `read:agent-tasks` | Read your agent tasks and their results |
| `read:asset-exports` | Read the status of your asset exports and download them |
| `read:assets` | Read the assets installed at your properties |
| `read:draft-orders` | Read draft orders you have created |
| `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:product-suppliers` | Read the suppliers whose products you can search |
| `read:products` | Read the product catalog |
| `read:projects` | Read projects and their phases |
| `read:pros` | Read the pros in your network |
| `test:permission` | Reserved for verifying that scope enforcement works end to end |
| `write:agent-tasks` | Create agent tasks and send messages and feedback |
| `write:change-requests` | Approve and reject change requests |
| `write:offers` | Create and modify offers |
| `write:phase-comments` | Post, edit, and delete comments on project phases |
| `write:phase-images` | Upload and attach images to project phases |
| `write:phase-schedule` | Propose, confirm, and decline project phase schedules |

`*` 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](/rest/test-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

REST endpoints do not accept GraphQL tokens. Every REST endpoint refuses one with `403 REST_TOKEN_REQUIRED`. The
endpoints that accepted GraphQL tokens before scopes existed stopped on October 1, 2026. GraphQL tokens continue to work
with the public GraphQL API.

To migrate, 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](https://developer.sibipro.com/), or have the token revoke itself:

```bash
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.