SIGNALS Docs
Reader View

Getting started: running Signals headless

Drive Signals from your own systems — integration users and roles, API tokens and abilities, the REST API and Explorer, MCP clients, webhooks, plugins, usage limits and a go-live checklist.

Overview

Running Signals headless means your own systems do the day-to-day work: a website books rentals, an accounting package reads invoices, an AI agent answers questions, a warehouse tool reacts to events. Signals stays the system of record, and integrations reach it through four surfaces:

Surface Use it for Start here
REST API v1 Reading and writing records from your code API Overview
MCP server AI clients that call Signals as tools MCP server
Webhooks Being told when something changes, instead of polling Webhooks
Plugins Code that runs inside Signals: fields, pages, workflow steps, tools Plugin SDK overview

There is no separate headless switch. The web app keeps running, and an administrator uses it once to set up the people, tokens and policies below. After that, your integrations need nothing from the browser.

This guide walks through that setup in order and ends with a checklist. Each step links to the page that covers it in full.

In the app, Extending → Developer Getting Started (admins only) opens with a short "Why run Signals headless?" intro the first time, then turns the same steps into a live checklist. Each step ticks itself once it is done on your install, starting with a dedicated integration user, and the page shows your own API and MCP URLs with copyable curl, SDK, MCP client and webhook snippets. Admins can also reach it from the Running Signals headless? card under the steps in Getting Started.

Why run Signals headless?

Your systems call the REST API and the MCP server and receive webhooks. Those requests go through the same permissions and records as the Signals app, and every change lands in the same history. Staff can keep using the app alongside.

  • Your own front end. Take bookings and show availability on your website through the REST API.
  • Automate the busywork. Webhooks tell your systems when records change, and signed inbound requests can start workflows.
  • AI agents via MCP. Agents call Signals as tools with a scoped token, and read-only mode keeps a first trial safe.
  • Connect what you already run. Keep accounts, ERP and warehouse tools in step, matching records by your own IDs. See Integration identities.

What you take on, compared with using the app:

Driving Signals headless Using the Signals app
Interface Yours to design, build and host Ready to use and updated with each release
Signing in A token per integration that you keep and rotate Passwords, two-factor, single sign-on or magic links
Limits Metered in units; handle 429 and Retry-After Not metered
Coverage The documented v1 API; some app settings are not exposed Every screen and setting
Upkeep Keep your code current with API versions Nothing to maintain
Rules and history Same permissions, same audit history Same permissions, same audit history

Most teams use both: people work in the app, and other systems use the API.

Before you start

  • Signals is installed and the setup wizard is finished. See Installation and First Run.
  • You know the install's base URL, for example https://rentals.example.com. Every API path below hangs off it.
  • You can sign in as the owner or as a user with admin access.

1. Users, roles and permissions

Signals has no special "service user" type. An integration acts as an ordinary user, so give each integration its own user rather than borrowing a person's account. Its actions are then attributed to it in history and logs, and you can revoke it without touching anyone else.

  1. Choose a role. The built-in roles are Administrator, Operations Manager, Sales, Warehouse and Read Only, and you can build your own in Admin → Users & Security → Roles. The owner is a flag on one user, not a role, and passes every permission check. See Roles & permissions.
    • A user that creates its own API token needs the Administrator role, because tokens are made in the admin area (step 2). Limit what the integration can do with the token's abilities instead.
    • A user that connects only through MCP with OAuth or a CLI connection grant never opens the admin area, so it can hold a narrower role. The abilities are approved for that connection instead of on a token.
  2. Invite the integration user in Admin → Users & Security → Users with that role. See Users. Inviting through the API is POST /api/v1/users, which needs the users.invite permission and a token with the users:write ability.
  3. Grant the integration permissions the user needs on top of its domain permissions:
Permission Unlocks
api.access Creating API tokens, the API Console at /api, the interactive reference at /docs/api
api.explorer.use The API Explorer at /api/explorer
api.logs.view The request log at /api/logs
api.usage.view The usage dashboard at /api/usage
webhooks.manage Outbound webhooks and inbound sources at /api/webhooks
mcp.access Connecting an MCP client
cli.access Running signals:api call from the terminal

Every API request is checked twice: the user must hold the permission for the action, and the token must carry the matching ability. Both have to allow it, so an Admin user with a tightly scoped token can still only do what the token allows.

2. API tokens and abilities

Tokens are personal access tokens. Each one belongs to the user who creates it, so sign in as the integration user to make its token.

  1. Open Admin → Users & Security → API (/admin/settings/api), Tokens tab. The page needs admin access, and creating a token needs api.access.
  2. Name the token after the integration, for example Website bookings.
  3. Tick only the abilities the integration uses. Abilities are resource:action strings such as rentals:read, rentals:write, accounts:read, catalogue-items:read, webhooks:manage and api-usage:read. Read-only and read-write are not token types: a token that only has :read abilities is read-only.
  4. Copy the token when it is shown. It is displayed once.

Tokens expire after the number of days in the API policy tab (api.token_expiration_days, default 365; 0 sets no expiry). Revoke a token on the same page, or with DELETE /api/v1/api-tokens/{token} using a token that has api-tokens:manage. Keep tokens in your secret manager, never in source control.

Full detail: API Tokens and Authentication.

3. REST API v1 and the Explorer

Every endpoint lives under /api/v1/ and speaks JSON with a bearer token:

curl -H "Authorization: Bearer <token>" \
     -H "Accept: application/json" \
     https://rentals.example.com/api/v1/me

GET /api/v1/me is the best first call: it returns who the token acts as, their roles, the token's abilities and the remaining quota. If it works, authentication is set up correctly.

Ways to explore the API:

  • API Explorer at /api/explorer: pick an endpoint, choose one of your saved tokens and send real requests from the browser. See API Console.
  • Interactive reference at /docs/api, with the OpenAPI document at /docs/api.json, on self-hosted installs. It needs api.access. See OpenAPI Reference.
  • PHP SDK for PHP integrations. See PHP SDK.
  • API CLI for scripts: php artisan signals:api list, describe and call, once API CLI is enabled in Admin → Users & Security → MCP & CLI. See API CLI.

Read API Conventions before writing code: it covers pagination, filter[field][operator] filters, errors, idempotency and long-running operations. To match your own IDs to Signals records, see Integration identities.

4. MCP server for AI clients

The MCP server exposes the same /api/v1 surface to AI clients as tools. Requests go through the same permission and ability checks as the REST API.

  1. Open Admin → Users & Security → MCP & CLI (/admin/settings/mcp-cli) and turn on MCP server. Keep HTTP transport on for remote clients. The page shows your endpoint, normally https://<your-install>/mcp/api.
  2. Make sure the connecting user holds mcp.access.
  3. Connect the client:
    • Claude Code with a token: claude mcp add --transport http signals https://<your-install>/mcp/api --header "Authorization: Bearer <token>". The settings page shows this command ready to copy.
    • Claude and Claude Desktop add it as a custom connector by URL and sign in with OAuth. There is no token to paste, and you approve the abilities on the consent screen.
    • Other clients take the URL plus an Authorization: Bearer <token> header.
    • Local agents can use stdio: approve a grant with php artisan signals:connection-grant approve, then run php artisan mcp:start signals-api with MCP_STDIO_USER and MCP_STDIO_CONNECTION set.
  4. Add mcp:execute to the token only if the client may use the open-ended execute-endpoint tool.

For an agent that should only look, turn on Read only (mcp.read_only). Write tools are hidden and execute-endpoint allows only GET. Full detail, including every tool: MCP server and MCP & CLI.

5. Webhooks, outbound and inbound

Outbound webhooks push events to your endpoint so you do not have to poll.

  • Create subscriptions in the API Console at /api/webhooks (needs webhooks.manage), or with /api/v1/webhooks and a token holding webhooks:manage. GET /api/v1/events lists every event you can subscribe to. See Webhook event catalogue.
  • Each delivery is signed. Verify the X-Signals-Signature header, an HMAC-SHA256 of {timestamp}.{body} made with the webhook's secret, and reject requests whose X-Signals-Timestamp is more than five minutes before receipt. Use X-Signals-Event-Id to ignore a delivery you have already handled.
  • Failed deliveries are retried with back-off. A 4xx response is not retried, and a webhook that keeps failing is disabled. Use Test, Redeliver and Replay to recover.

Full detail: Webhooks.

Inbound webhooks let other systems call Signals. Each source you add on the Inbound tab of /api/webhooks gets its own receive URL, /webhooks/receive/{slug}, and a signing secret. Signals checks the HMAC signature on every request and refuses a bad one with 401. Workflows can also be started by a signed inbound request. See API Console, Inbound Delivery Tracking for message delivery receipts, and Plugin SDK vs Workflows vs Webhooks to pick the right tool.

6. Plugins and the SDK

When an integration needs to run inside Signals, for example to add fields, pages, workflow steps, dashboard widgets or MCP tools, build a plugin.

7. Rate limits, usage and logs

  • Metering. Authenticated requests are metered in weighted units rather than raw request counts. Responses carry X-Signals-Units-Charged, X-Signals-Units-Remaining, X-Signals-Units-Restore-Rate and X-Signals-Units-Daily-Remaining. A 429 comes with Retry-After, so back off for that long.
  • Unauthenticated requests are limited per IP address (api.rate_limit_unauthenticated, default 20 a minute).
  • Usage at /api/usage, or GET /api/v1/usage with api-usage:read, breaks requests and units down by token, endpoint, resource and status, for API calls and webhooks alike.
  • Request log at /api/logs, or GET /api/v1/request_logs with api-log:read, shows each call with its status and timing.
  • Prefer webhooks to polling. Polling an expensive endpoint every few seconds uses up units quickly, while a webhook tells you only when something changes.

Full detail: Usage & Metering and Authentication.

8. Testing safely

Signals has no separate sandbox mode, so test against an installation you can afford to change:

  • A second installation for staging, loaded with demo data. Use php artisan signals:seed-demo or Admin → Database Seeders, and remove it again with php artisan signals:clear-demo. See Seeders and Demo Data.
  • Idempotency keys. Send an Idempotency-Key header on every POST, so a retried request never creates a record twice. A replayed response carries Idempotency-Replayed: true. Turn on api.require_idempotency_key to refuse a POST without one.
  • Previews before writes. Several endpoints preview without saving, such as workflow dry runs, rental cascade and pricing previews, account merge previews and import validation. See the OpenAPI Reference.
  • Webhook test sends. Use Test on a subscription, or POST /api/v1/webhooks/{id}/test, to check your receiver before real events flow.
  • Read-only first. Start an MCP client with Read only on, and start each token with :read abilities. Widen them only once the integration behaves.

Checklist

  • Signals installed and first run finished.
  • A dedicated user for each integration: the Admin role when it creates its own token, a narrower role when it connects only through MCP OAuth or a CLI grant.
  • api.access, plus mcp.access, webhooks.manage or cli.access where the integration uses them.
  • A token per integration, named after it, with only the abilities it uses, stored in a secret manager.
  • Token expiry set in the API policy, and a reminder to rotate tokens before they expire.
  • GET /api/v1/me succeeds with each token.
  • MCP server enabled and the client connected, in read-only mode first if it is an agent.
  • Webhook receivers verify X-Signals-Signature and reject stale timestamps.
  • Every POST sends an Idempotency-Key.
  • Your client honours 429 and Retry-After, and you have checked /api/usage after a test run.
  • End-to-end tests run against a staging installation with demo data, not production.

Administrator role changes

The built-in role is Administrator; send roles: ["Administrator"] when creating or updating users. Its ID and assignments survive the rename from Admin. is_admin is a deprecated, read-only projection of Administrator-role membership. An owner without that role returns false. Sending is_admin in a user write returns 422; use role assignments instead. filter[is_admin][eq] still filters by role membership.