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:
- Go to Manage → Staff, click the ⋮ menu (top right), and choose Manage Roles.
- 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.