Authentication & tokens

Every API call is authenticated with a Bearer token. Each company has exactly one token, and it can only do what its scopes — real ERP permissions — allow.

The Bearer token

Tokens look like redz_live_<hex>. Send yours in the Authorization header on every request:

GET /v1/projects HTTP/1.1
Host: api.redz.build
Authorization: Bearer redz_live_1a2b3c...

A missing or unknown/revoked token returns 401 with a WWW-Authenticate: Bearer challenge.

One token per company

  • Open Settings ▸ API in the ERP and issue the token. The key is shown on demand — copy it then, and store it as a secret.
  • There is a single active token per company. Rotating it mints a new key with the same scopes and immediately stops the old one.
  • Revoking the token disables API access until you issue a new one.

Scopes are permission codes

A token carries a list of scopes, and each scope is an ERP permission code such as PROJECTS_VIEW, CLIENTS_EDIT or EQUIPMENT_DELETE. When you issue the token you tick the permissions to grant — you can only grant rights you hold yourself.

At request time a call is allowed only when the endpoint’s required scope is both on the token and still held by the account. If it is missing the call returns 403 insufficient_scope naming the scope needed.

OperationExample scope
List / get<RESOURCE>_VIEW
Create / update<RESOURCE>_EDIT
Delete<RESOURCE>_DELETE

Optional IP allowlist

You can bind the token to one or more source IPs or IPv4 CIDR ranges. A request from any other address is rejected with 403. Leave the allowlist empty to accept calls from anywhere. The check uses the real TCP peer address, so a spoofed X-Forwarded-For cannot bypass it.

Least privilege. Grant a token only the scopes an integration truly needs, and add an IP allowlist for server-to-server use. If a key leaks, rotate it — the old one dies instantly.
On this page
Docs

Frequently asked questions

No &mdash; there is one active token per company. If you need to change what an integration can do, update its scopes or rotate the key.

It stops working immediately. Rotation keeps the same scopes, label and IP allowlist but issues a brand-new key that you must copy again.

The scope must also still be held by the underlying account. If the permission was removed from the user who created the token, the API honours that revocation and returns 403.