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 > Settings > API or programmatically via the API.

Creating a Token#

Navigate to Admin > Settings > 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.

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.

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#

API requests are rate-limited per token (or per client IP when unauthenticated). Default limits, configurable in Admin > Settings > API:

An individual token can be given a bespoke per-minute limit (rate_limit_per_minute) from the API Tokens admin screen, overriding the authenticated default. Every response carries rate-limit headers:

• X-RateLimit-Limit — maximum requests per window
• X-RateLimit-Remaining — requests remaining
• Retry-After — seconds until the limit resets (sent on 429)

Rate limiting counts requests. It is separate from usage metering, where each endpoint has a price weight (most are 1, meta endpoints are 0) that is summed into billable weighted units — see Usage & Metering.

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, the Laravel error shape, offset pagination, Ransack-style filtering, sorting, includes, and sparse fieldsets are identical across every v1 endpoint — they are documented once in API Conventions.