How do I prepare my API tokens for permission enforcement on Companies, Contacts, and Invoices?

Last updated: September 29, 2026

Overview

Luminous is rolling out role-based permission enforcement on the External V1 API. The Companies, Contacts, and Invoices resource families are the latest to be included. Once enforcement is enabled for your account, the API authenticates calls using the token's owner user, so the owner must hold the relevant role permission — just as they would need it inside the Luminous app — or the call returns a 403 Forbidden.

This is a per-account opt-in. While the feature is off for your account, every existing token continues to work exactly as today.


Permission requirements by endpoint

Companies

Action

Endpoints

Permission required

Read

GET /companies, GET /companies/{id}

Read Companies

Create / Update / Delete

POST /companies, POST /companies/{id}, DELETE /companies/{id}

Update Companies

Contacts

Action

Endpoints

Permission required

Read

GET /contacts, GET /contacts/{id}, GET /companies/{id}/contacts

Read Company Contacts

Create / Update / Delete

POST /contacts, POST /contacts/{id}, DELETE /contacts/{id}, POST /contacts/{id}/b2b-portal-password

Update Companies

Invoices

Action

Endpoints

Permission required

Read

GET /invoices, GET /invoices/{id}

Read Invoices

Create

POST /invoices

Create Invoices

Update

PATCH /invoices/{id}

Update Invoices

Approve or Reject

POST /invoices/{id}/approve, POST /invoices/{id}/reject

Approve Invoices

Note: Invoice tag and custom-field sub-resources (/invoices/{id}/tags, /invoices/{id}/custom-fields) are not gated by permission on the external API.


Who is always safe?

Users assigned to the Admin, Super Admin, or Factory Admin tier automatically hold all of the permissions listed above. If every API token in your account is owned by an admin-tier user, enabling enforcement will have no effect on your integrations.


How to audit your tokens before opting in

Ask your Luminous contact to run a token audit before enforcement is turned on for your account. It checks every active API token and flags any whose owner is missing a required permission.

To review permissions yourself:

  1. Go to Manage → Staff, click the ⋮ menu (top right), and choose Manage Roles.

  2. For each role used by staff who own API tokens, confirm it includes the permissions below for the resources your integrations use.

Note: the API Tokens page (Settings → API Tokens) doesn't show which user owns each token. If you're not sure who created a token, ask your Luminous contact.

What happens if a token lacks permission after enforcement is enabled?

The API returns:

HTTP 403 Forbidden

The response body follows the standard Luminous error envelope. To resolve it, either:

  • Add the missing permission to the owner's role, or

  • Re-create the token under a user whose role already holds the permission.

No data is modified — the request is simply refused at the route before it reaches any business logic.