SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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.

AbilityDescription
accounts:readRead accounts
accounts:writeWrite accounts
action-log:readRead action logs
activities:readRead activities
activities:writeWrite activities
addresses:readRead the Global Address List
addresses:writeCreate, update, and delete addresses
api-log:readRead API request logs
api-tokens:manageList and revoke your own personal access tokens
api-usage:readRead API usage aggregates
approvals:readRead policy-permitted approval requests and history
approvals:writeApprove or reject assigned approval requests
asset-costs:readRead structured maintenance cost history and TCO rollups
asset-costs:writeRecord, update, and delete asset cost entries
asset-retirements:readRead asset retirement records and retired asset state
asset-retirements:writeRetire, void, and reinstate barcoded assets
assets:readRead assets & ledger
assets:writeWrite assets & adjustments
availability:readRead catalogue item availability
catalogue-items:readRead catalogue items & catalogue item groups
catalogue-items:writeWrite catalogue items & catalogue item groups
channel-providers:readRead notification channel provider configuration
channel-providers:writeCreate, update, delete, and test channel providers
communication-templates:readRead communication templates and version history
communication-templates:writeCreate, update, delete, and restore communication templates
communications:approveApprove, discard, and send drafted customer communications
communications:draftCompose customer communication drafts for human approval
communications:readRead communication log entries
conversations:readRead conversations and comments
conversations:writeCreate, update, delete conversations and comments
countries:readRead countries
credit-notes:readRead credit notes
credit-notes:writeIssue credit notes against invoices
currencies:readRead currencies
custom-fields:readRead custom fields
custom-fields:writeWrite custom fields
dashboards:readRead personal dashboards, visible shares and permitted widget data
dashboards:writeManage personal dashboards and publish permitted shared snapshots
documents:readRead generated documents and templates
documents:writeGenerate, finalise, and share documents
email-layouts:readRead email layouts and version history
email-layouts:writeCreate, update, delete, default, and restore email layouts
email-templates:readRead email templates and version history
email-templates:writeUpdate, reset, and restore email templates
equipment-test-results:readRead equipment test execution history
equipment-test-results:writePerform and delete equipment test results
equipment-tests:readRead equipment test definitions
equipment-tests:writeCreate, update, and delete equipment test definitions
equipment_tests:readRead equipment test definitions
equipment_tests:writeCreate, update, and delete equipment test definitions
events:readRead the domain event catalogue
evidence:readRead the evidence ledger: proposed facts, their scores, and their provenance
exchange-rates:readRead exchange rates
exchange-rates:writeWrite exchange rates
exchange_rates:readRead exchange rates
exchange_rates:writeWrite exchange rates
exports:readRead export job status and download completed files
exports:writeCreate and cancel data exports
facilities:readRead scheduling facilities
facilities:writeWrite scheduling facilities
flightcases:readRead flightcases & contents
flightcases:writeCreate, update, pack & unpack flightcases
imports:readRead import batches, plans, mappings, and profiles
imports:writeUpload imports, execute plans, set mappings, and manage profiles
invoices:readRead invoices and payments
invoices:writeCreate and manage invoices
kits:readRead kit compositions
kits:writeManage kit compositions
live-filters:readRead saved list views
live-filters:writeCreate, update, clone, and delete saved list views
mcp:executeRun arbitrary API endpoints through MCP execute-endpoint
notification-preferences:readRead user and account notification preferences
notification-preferences:writeUpdate user and account notification preferences
notification-settings:readRead tenant notification type settings
notification-settings:writeUpdate tenant notification type settings
payments:readRead invoice payments
payments:writeRecord and manage invoice payments
phase-definitions:readRead configured rental phase definitions
phase-definitions:writeCreate, preview impact, edit, archive, and restore rental phase definitions
plugins:readRead installed plugins and manifests
plugins:writeEnable, disable, and manage plugins
pricing:readRead discount groups and rate bands
pricing:writeWrite discount groups and rate bands
projects:readRead rental project records
projects:writeCreate, update, and delete rental projects; attach and detach rentals
purchase-orders:readRead purchase orders and lines
purchase-orders:writeCreate and manage purchase orders
purchase_orders:readRead purchase orders and lines
purchase_orders:writeCreate and manage purchase orders
rates:readRead rate specifications & catalogue item prices
rates:writeWrite rate specifications & catalogue item prices
rentals:readRead rentals
rentals:writeWrite rentals
repairs:readRead repair records
repairs:writeRaise, update, and release repairs
reports:askDraft reports using the configured AI text provider
reports:readRead saved reports, visible folders and permitted run history, and run reports
reports:writeCreate, update, delete and pin saved reports, and manage public snapshot links
resource-assignments:readRead scheduling resource assignments
resource-assignments:writeWrite scheduling resource assignments
roles:readRead roles
roles:writeWrite roles
scanning:readRead scannable identifiers and scan sessions
scanning:writeOpen and manage scan sessions, and submit individual or bulk scans
scheduling-conflicts:readRead scheduling conflict records
scheduling-conflicts:writeAcknowledge or resolve scheduling conflict records
schema:readRead schema / field metadata
search:readSearch across every registered searchable entity type
services:readRead labour catalogue services
services:writeWrite labour catalogue services
settings:readRead all settings groups
settings:read:accountsRead the accounts settings group only
settings:read:action-logRead the action-log settings group only
settings:read:aiRead the ai settings group only
settings:read:ai-textRead the ai_text settings group only
settings:read:ai_textRead the ai_text settings group only
settings:read:apiRead the api settings group only
settings:read:api-cliRead the api_cli settings group only
settings:read:api_cliRead the api_cli settings group only
settings:read:approvalsRead the approvals settings group only
settings:read:availabilityRead the availability settings group only
settings:read:brandingRead the branding settings group only
settings:read:cacheRead the cache settings group only
settings:read:colourRead the colour settings group only
settings:read:companyRead the company settings group only
settings:read:dashboardRead the dashboard settings group only
settings:read:emailRead the email settings group only
settings:read:financeRead the finance settings group only
settings:read:importsRead the imports settings group only
settings:read:integrationsRead the integrations settings group only
settings:read:invoicesRead the invoices settings group only
settings:read:localisationRead the localisation settings group only
settings:read:maintenanceRead the maintenance settings group only
settings:read:mapsRead the maps settings group only
settings:read:mcpRead the mcp settings group only
settings:read:nightwatchRead the nightwatch settings group only
settings:read:notificationsRead the notifications settings group only
settings:read:paymentsRead the payments settings group only
settings:read:preferencesRead the preferences settings group only
settings:read:pricingRead the pricing settings group only
settings:read:rentalsRead the rentals settings group only
settings:read:reportsRead the reports settings group only
settings:read:schedulingRead the scheduling settings group only
settings:read:searchRead the search settings group only
settings:read:securityRead the security settings group only
settings:read:ssoRead the sso settings group only
settings:read:stock-checksRead the stock_checks settings group only
settings:read:stock_checksRead the stock_checks settings group only
settings:read:taxRead the tax settings group only
settings:read:uploadsRead the uploads settings group only
settings:read:webhooksRead the webhooks settings group only
settings:read:workflowsRead the workflows settings group only
settings:writeWrite settings
shortages:readRead shortages & resolutions
shortages:writeWrite shortage resolutions
static-data:readRead static data (lists)
static-data:writeWrite static data (lists)
stock-checks:readRead stock check records
stock-checks:writeCreate, count, close, and reopen stock checks
stock_checks:readRead stock check records
stock_checks:writeCreate, count, close, and reopen stock checks
system:readRead system info
tax-types:readRead tax types
tax-types:writeWrite tax types
usage-readings:readRead cumulative usage reading history
usage-readings:writeRecord cumulative usage readings
users:readRead users
users:writeWrite users
vehicles:readRead fleet vehicles
vehicles:writeWrite fleet vehicles
virtual-stock:readRead virtual stock intakes
virtual-stock:writeCreate and manage virtual stock intakes
virtual_stock:readRead virtual stock intakes
virtual_stock:writeCreate and manage virtual stock intakes
warehouse-transfers:readRead warehouse transfer records
warehouse-transfers:writeCreate, dispatch, receive, and cancel warehouse transfers
warehouse_transfers:readRead warehouse transfer records
warehouse_transfers:writeCreate, dispatch, receive, and cancel warehouse transfers
warehouses:readRead warehouse locations
warehouses:writeCreate, update, and delete warehouse locations
webhooks:manageManage webhooks
workflows:readRead workflow definitions, versions, and run summaries
workflows:writeCreate, 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_ids is a list for a scoped token and null for unrestricted all-warehouse access.
  • default_warehouse_id prefers the installation's default warehouse when it is accessible, otherwise the first accessible warehouse; it is null when 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.