Authentication
How to authenticate with the Signals API using bearer tokens.
Authentication
The Signals API uses Bearer tokens issued via Laravel Sanctum. Generate tokens from the admin panel at Admin > Users & Security > API.
Creating a Token
Navigate to Admin > Users & Security > API in the web interface. Click Create Token, name your token, select the abilities it should have, and click Generate. The token value is shown once — copy it immediately.
Using a Token
Include the token in the Authorization header of every API request:
Authorization: Bearer {your-token}
All requests must also include Accept: application/json.
Expiry and revocation
Tokens expire after the configured lifetime: 365 days by default, with a maximum of 3,650 days. A setting of 0 turns off policy-based expiry. Expired tokens return 401, and the refusal is audited without recording the secret. See token lifetime for policy-based expiry and administrator-set deadlines.
GET /api/v1/api-tokens (api.v1.api-tokens.index) returns up to 100 recent visible tokens with their ID, name, expiry, last-used time, and creation time. Administrators with users.view can inspect other users' tokens; other users see their own. Token secrets are never returned.
DELETE /api/v1/api-tokens/{token} (api.v1.api-tokens.destroy) revokes one of your own tokens and returns 204. Unknown IDs and other users' IDs are an idempotent no-op. Both endpoints require api.access and the api-tokens:manage token ability. MCP exposes the same own-token action as revoke-api-token with a token_id argument.
Revocation takes effect on the next REST or MCP request. Deactivation, removed roles or abilities, and signing out everywhere also revoke or restrict access immediately.
Token Abilities
Tokens are scoped with abilities in resource:action form (e.g. accounts:read,
invoices:write). A request whose token lacks the required ability is rejected
with 403; a missing or invalid token returns 401. The complete catalogue of
registered abilities is below — grant a token only the abilities it needs.
Canonical multi-word ability names use kebab case. Their historical snake-case
aliases remain listed and authorise interchangeably, so existing tokens do not
need to be reissued.
| Ability | Description |
|---|---|
accounts:read | Read accounts |
accounts:write | Write accounts |
action-log:read | Read action logs |
activities:read | Read activities |
activities:write | Write activities |
addresses:read | Read the Global Address List |
addresses:write | Create, update, and delete addresses |
api-log:read | Read API request logs |
api-tokens:manage | List and revoke your own personal access tokens |
api-usage:read | Read API usage aggregates |
approvals:read | Read policy-permitted approval requests and history |
approvals:write | Approve or reject assigned approval requests |
asset-costs:read | Read structured maintenance cost history and TCO rollups |
asset-costs:write | Record, update, and delete asset cost entries |
asset-retirements:read | Read asset retirement records and retired asset state |
asset-retirements:write | Retire, void, and reinstate barcoded assets |
assets:read | Read assets & ledger |
assets:write | Write assets & adjustments |
availability:read | Read catalogue item availability |
catalogue-items:read | Read catalogue items & catalogue item groups |
catalogue-items:write | Write catalogue items & catalogue item groups |
channel-providers:read | Read notification channel provider configuration |
channel-providers:write | Create, update, delete, and test channel providers |
communication-templates:read | Read communication templates and version history |
communication-templates:write | Create, update, delete, and restore communication templates |
communications:approve | Approve, discard, and send drafted customer communications |
communications:draft | Compose customer communication drafts for human approval |
communications:read | Read communication log entries |
conversations:read | Read conversations and comments |
conversations:write | Create, update, delete conversations and comments |
countries:read | Read countries |
credit-notes:read | Read credit notes |
credit-notes:write | Issue credit notes against invoices |
currencies:read | Read currencies |
custom-fields:read | Read custom fields |
custom-fields:write | Write custom fields |
dashboards:read | Read personal dashboards, visible shares and permitted widget data |
dashboards:write | Manage personal dashboards and publish permitted shared snapshots |
documents:read | Read generated documents and templates |
documents:write | Generate, finalise, and share documents |
email-layouts:read | Read email layouts and version history |
email-layouts:write | Create, update, delete, default, and restore email layouts |
email-templates:read | Read email templates and version history |
email-templates:write | Update, reset, and restore email templates |
equipment-test-results:read | Read equipment test execution history |
equipment-test-results:write | Perform and delete equipment test results |
equipment-tests:read | Read equipment test definitions |
equipment-tests:write | Create, update, and delete equipment test definitions |
equipment_tests:read | Read equipment test definitions |
equipment_tests:write | Create, update, and delete equipment test definitions |
events:read | Read the domain event catalogue |
evidence:read | Read the evidence ledger: proposed facts, their scores, and their provenance |
exchange-rates:read | Read exchange rates |
exchange-rates:write | Write exchange rates |
exchange_rates:read | Read exchange rates |
exchange_rates:write | Write exchange rates |
exports:read | Read export job status and download completed files |
exports:write | Create and cancel data exports |
facilities:read | Read scheduling facilities |
facilities:write | Write scheduling facilities |
flightcases:read | Read flightcases & contents |
flightcases:write | Create, update, pack & unpack flightcases |
imports:read | Read import batches, plans, mappings, and profiles |
imports:write | Upload imports, execute plans, set mappings, and manage profiles |
invoices:read | Read invoices and payments |
invoices:write | Create and manage invoices |
kits:read | Read kit compositions |
kits:write | Manage kit compositions |
live-filters:read | Read saved list views |
live-filters:write | Create, update, clone, and delete saved list views |
mcp:execute | Run arbitrary API endpoints through MCP execute-endpoint |
notification-preferences:read | Read user and account notification preferences |
notification-preferences:write | Update user and account notification preferences |
notification-settings:read | Read tenant notification type settings |
notification-settings:write | Update tenant notification type settings |
payments:read | Read invoice payments |
payments:write | Record and manage invoice payments |
phase-definitions:read | Read configured rental phase definitions |
phase-definitions:write | Create, preview impact, edit, archive, and restore rental phase definitions |
plugins:read | Read installed plugins and manifests |
plugins:write | Enable, disable, and manage plugins |
pricing:read | Read discount groups and rate bands |
pricing:write | Write discount groups and rate bands |
projects:read | Read rental project records |
projects:write | Create, update, and delete rental projects; attach and detach rentals |
purchase-orders:read | Read purchase orders and lines |
purchase-orders:write | Create and manage purchase orders |
purchase_orders:read | Read purchase orders and lines |
purchase_orders:write | Create and manage purchase orders |
rates:read | Read rate specifications & catalogue item prices |
rates:write | Write rate specifications & catalogue item prices |
rentals:read | Read rentals |
rentals:write | Write rentals |
repairs:read | Read repair records |
repairs:write | Raise, update, and release repairs |
reports:ask | Draft reports using the configured AI text provider |
reports:read | Read saved reports, visible folders and permitted run history, and run reports |
reports:write | Create, update, delete and pin saved reports, and manage public snapshot links |
resource-assignments:read | Read scheduling resource assignments |
resource-assignments:write | Write scheduling resource assignments |
roles:read | Read roles |
roles:write | Write roles |
scanning:read | Read scannable identifiers and scan sessions |
scanning:write | Open and manage scan sessions, and submit individual or bulk scans |
scheduling-conflicts:read | Read scheduling conflict records |
scheduling-conflicts:write | Acknowledge or resolve scheduling conflict records |
schema:read | Read schema / field metadata |
search:read | Search across every registered searchable entity type |
services:read | Read labour catalogue services |
services:write | Write labour catalogue services |
settings:read | Read all settings groups |
settings:read:accounts | Read the accounts settings group only |
settings:read:action-log | Read the action-log settings group only |
settings:read:ai | Read the ai settings group only |
settings:read:ai-text | Read the ai_text settings group only |
settings:read:ai_text | Read the ai_text settings group only |
settings:read:api | Read the api settings group only |
settings:read:api-cli | Read the api_cli settings group only |
settings:read:api_cli | Read the api_cli settings group only |
settings:read:approvals | Read the approvals settings group only |
settings:read:availability | Read the availability settings group only |
settings:read:branding | Read the branding settings group only |
settings:read:cache | Read the cache settings group only |
settings:read:colour | Read the colour settings group only |
settings:read:company | Read the company settings group only |
settings:read:dashboard | Read the dashboard settings group only |
settings:read:email | Read the email settings group only |
settings:read:finance | Read the finance settings group only |
settings:read:imports | Read the imports settings group only |
settings:read:integrations | Read the integrations settings group only |
settings:read:invoices | Read the invoices settings group only |
settings:read:localisation | Read the localisation settings group only |
settings:read:maintenance | Read the maintenance settings group only |
settings:read:maps | Read the maps settings group only |
settings:read:mcp | Read the mcp settings group only |
settings:read:nightwatch | Read the nightwatch settings group only |
settings:read:notifications | Read the notifications settings group only |
settings:read:payments | Read the payments settings group only |
settings:read:preferences | Read the preferences settings group only |
settings:read:pricing | Read the pricing settings group only |
settings:read:rentals | Read the rentals settings group only |
settings:read:reports | Read the reports settings group only |
settings:read:scheduling | Read the scheduling settings group only |
settings:read:search | Read the search settings group only |
settings:read:security | Read the security settings group only |
settings:read:sso | Read the sso settings group only |
settings:read:stock-checks | Read the stock_checks settings group only |
settings:read:stock_checks | Read the stock_checks settings group only |
settings:read:tax | Read the tax settings group only |
settings:read:uploads | Read the uploads settings group only |
settings:read:webhooks | Read the webhooks settings group only |
settings:read:workflows | Read the workflows settings group only |
settings:write | Write settings |
shortages:read | Read shortages & resolutions |
shortages:write | Write shortage resolutions |
static-data:read | Read static data (lists) |
static-data:write | Write static data (lists) |
stock-checks:read | Read stock check records |
stock-checks:write | Create, count, close, and reopen stock checks |
stock_checks:read | Read stock check records |
stock_checks:write | Create, count, close, and reopen stock checks |
system:read | Read system info |
tax-types:read | Read tax types |
tax-types:write | Write tax types |
usage-readings:read | Read cumulative usage reading history |
usage-readings:write | Record cumulative usage readings |
users:read | Read users |
users:write | Write users |
vehicles:read | Read fleet vehicles |
vehicles:write | Write fleet vehicles |
virtual-stock:read | Read virtual stock intakes |
virtual-stock:write | Create and manage virtual stock intakes |
virtual_stock:read | Read virtual stock intakes |
virtual_stock:write | Create and manage virtual stock intakes |
warehouse-transfers:read | Read warehouse transfer records |
warehouse-transfers:write | Create, dispatch, receive, and cancel warehouse transfers |
warehouse_transfers:read | Read warehouse transfer records |
warehouse_transfers:write | Create, dispatch, receive, and cancel warehouse transfers |
warehouses:read | Read warehouse locations |
warehouses:write | Create, update, and delete warehouse locations |
webhooks:manage | Manage webhooks |
workflows:read | Read workflow definitions, versions, and run summaries |
workflows:write | Create, publish, activate, and run workflows |
Sending communications
communications:read has no communications:write counterpart, and this is
deliberate. The ability covers reading the communication log; outbound sending
is never gated by a communications:write ability. Sends happen as a side
effect of the domain action that produces them — a document send, for example,
is authorised by that document's own ability — so the permission to send is
always the permission to perform the underlying business operation. Whether a
particular action type may send autonomously (and who must sign it off) is the
approval layer's concern, not a token scope.
Rate Limiting
Authenticated API traffic is metered in weighted units per principal (token
or OAuth/MCP/CLI connection), not counted in requests per minute. Each principal
has a continuously restoring unit bucket and a daily cap (config/api_metering.php,
throughput.standard / throughput.high). Responses carry
X-Signals-Units-Charged, X-Signals-Units-Remaining,
X-Signals-Units-Restore-Rate and X-Signals-Units-Daily-Remaining; the live
quota is also available from GET /api/v1/me.
Enforcement is off by default (API_METERING_THROUGHPUT_ENFORCE=false): an
over-budget request is logged and still served. When enforcement is enabled,
over-budget requests receive 429 with Retry-After, a zero short-term remaining balance and the current daily balance. The refusal omits X-Signals-Units-Charged. Each endpoint's price weight (most are 1, meta endpoints are 0) is
also summed into billable usage — see Usage & Metering.
Unauthenticated requests use a flat per-IP limit (default 20 requests/minute,
Admin > Users & Security > API). The per-minute authenticated limit (default 60) and a
token's bespoke rate_limit_per_minute apply only if unit throughput metering is
disabled (API_METERING_THROUGHPUT_ENABLED=false).
Token introspection
GET /api/v1/me is available to any authenticated token and reports identity,
roles, granted and grouped abilities, rate and unit quota, and whether strict
idempotency is enabled. It also reports warehouse access using the same ACL as
API queries:
warehouse_idsis a list for a scoped token andnullfor unrestricted all-warehouse access.default_warehouse_idprefers the installation's default warehouse when it is accessible, otherwise the first accessible warehouse; it isnullwhen the caller cannot access any warehouse.
Idempotency
Any side-effecting POST accepts an optional Idempotency-Key header; replaying
the same key returns the stored response with Idempotency-Replayed: true.
Operators can enable strict mode (api.require_idempotency_key) to require
the header on every mutating POST /api/v1/... request (428 if missing).
GET/PUT/PATCH/DELETE and unauthenticated endpoints are never affected.
See API Conventions → Idempotency for the full contract.
Response, errors, pagination & filtering
Response envelopes, errors, offset and cursor pagination, filter[field][operator]
filtering, sorting, includes, and sparse fieldsets follow API Conventions. Each endpoint publishes its supported filters, includes and pagination modes.
Tokens issued without an explicit deadline use the current default lifetime measured from issuance. Increasing the default extends those tokens; explicit administrator-set expiries remain unchanged.
API Console browser sessions
The HTML pages GET /api, /api/explorer, /api/logs, /api/usage and /api/webhooks require a signed-in browser session. OpenAPI declares browserSession authentication through the Cookie header. A bearer token does not authenticate those pages. In Postman, set session_cookie to the authorized session cookie for these requests; REST operations continue to use bearer tokens.