Integrations
Geocoding, single sign-on, AI embeddings, AI (text), Stripe payments, the exchange rate provider, and self-hosted monitoring.
Overview
Integrations covers third-party credentials. The page has one tab per service, in this order: Geocoding, Single Sign-On, AI embeddings, AI (text), Payments, Exchange rates, and (self-hosted only) Monitoring. Each tab can be linked directly with ?tab=geocoding, sso, ai, ai_text, payments, exchange_rates or monitoring.
Where it lives
Route: /admin/settings/integrations (admin.settings.integrations)
Open Admin → Preferences → Integrations. Requires settings.manage.
Sections
Geocoding
- what3words API Key (masked)
Single Sign-On
- Google and Microsoft 365 enable toggles
- Self-hosted: client ID, write-only client secret, Microsoft directory (tenant) ID, and a copyable Redirect / Callback URL
- Allowed email domains (normalised, deduplicated)
- Require auth_time for confirmation, independently for Google and Microsoft (
sso.google_require_auth_timeandsso.microsoft_require_auth_time), off by default
Provider confirmation requests re-login with prompt=login and max_age=0. If the verified ID token supplies auth_time, it must be recent; stale or malformed values are always refused. If it omits the claim, confirmation is accepted unless that provider's Require auth_time for confirmation setting is enabled. Enable this only after configuring the provider registration to emit the claim. Refused confirmations return to Confirm your identity with a message and an auth log reason.
On Signals Cloud, SSO credential fields are hidden; toggles and the allow-list remain editable.
AI embeddings
The tab opens with three status cards: AI search (Off, Needs API key, Needs consent, Endpoint refused, Database not ready, Paused, Paused — budget reached, or On, with the next step), Tokens this month across all AI features against the monthly budget, and Report questions (the AI (text) and Reports settings state). Settings are grouped into Provider and key, On or off, What gets indexed and Budget and upkeep, saved with Save AI Settings. Consent and data sharing shows the privacy notice and who consented and when; owners use Give Consent or Revoke Consent (revoking deletes every stored vector). Usage lists token totals by period and by feature.
Enable embeddings, API key, provider/model (openai / gemini / mistral, or openai_compatible for a bring-your-own endpoint), refresh cadence, monthly token budget, usage retention, and pause sync. Choosing openai_compatible swaps the model dropdown for a base URL, model id, and dimensions — point it at Ollama, vLLM, or another OpenAI API server. Record text stays on your network when that server is local. Changing provider/model while enabled requires matching owner consent before generation resumes.
Custom endpoints default to public trust: HTTPS, verified TLS, port 443 and public addresses only. An operator can enable local HTTP and private/loopback endpoints with EMBEDDINGS_ENDPOINT_TRUST=local on a self-hosted install; this env-only opt-in has no AI-tab control and is ignored on Cloud. Local ports are 443, 80, 11434, 8000, 8080, 1234 and 8081. Metadata, link-local, multicast and reserved addresses remain blocked.
Endpoint validation explains refusals for credentials, query strings, fragments, ambiguous hosts, unsupported ports and unsafe API-root paths. A refused save leaves the stored value unchanged. Invalid env or stored endpoints disable embeddings and retain consent. Every call checks DNS again, pins a validated address and refuses redirects; TLS failures never fall back to HTTP. Keyword search remains available and unavailable embedding jobs skip cleanly. See endpoint trust and refusals for the complete policy.
On Cloud, credentials are platform-managed — see AI embeddings & configuration for behaviour and API details.
Additional embedding types can be selected individually. Rentals, accounts and catalogue items are included. The panel estimates record counts, vector bytes and input tokens; search-index storage is additional.
AI (text)
Used by Reports to turn a plain-English question into a report draft; separate from AI embeddings. Only the question and the names of the report fields the person may use are sent — never report rows.
Fields: Provider, Model (leave blank for the suggested model), and API key (stored encrypted, never shown again; Remove key clears it). Click Save AI (text) settings. Only an owner can change the provider. On Signals Cloud the provider and credentials are managed by Signals and shown read-only.
Payments
The tab's Stripe section holds Stripe credentials for customer portal invoice payments: publishable key, secret key, and webhook signing secret. All three are stored encrypted and are write-only — a blank input keeps the stored value, and stored secrets are never rendered back into the form.
Stored keys take precedence over the STRIPE_* environment variables; a blank setting falls back to the Cashier config, so env-configured installs are unaffected. See Document portal & payments.
Exchange rates
In the Exchange rate provider section, self-hosted installations can choose manual, the free daily European Central Bank feed, or Open Exchange Rates. Open Exchange Rates requires its application ID, stored encrypted and kept write-only. Fetch rates now runs the selected automatic provider immediately; the same fetch runs daily in the scheduler and records provider-owned pairs through the audited exchange-rate actions.
The stored integrations.exchange_rate_provider setting takes precedence over currency.exchange_rate_provider / the environment, so env-configured installs keep working until an admin saves a choice. Plugins can still register additional feed-backed providers on ExchangeRateProviderRegistry.
On Signals Cloud, the provider is platform-controlled (currency.cloud_provider, default ecb), so tenants see a cloud-provided message instead of provider credentials or controls. See Exchange Rates and Exchange Rate Provider Registry.
Monitoring (self-hosted)
The tab opens with status cards for Monitoring, the Nightwatch agent (running, started outside Signals, or stopped, with PID and uptime), the Agent port and the Ingest token. Set-up follows three numbered steps:
- Add your ingest token — write-only and encrypted; Validate Token checks it with Nightwatch without saving.
- Turn monitoring on and choose how much to capture — the enable switch and request sample rate (every request, 50%, 25%, 10% or 1%; a custom stored value stays selectable). Save Changes writes the values to
.env. - Run the agent — Start Agent, Stop Agent, Restart Agent or Take Over & Restart for an agent started elsewhere. In production run
php artisan nightwatch:agentunder supervisor or systemd.
What is sent to Nightwatch lists what is captured and not captured, the redacted form fields and headers, and the other sample rates, read from the NIGHTWATCH_* environment. Agent output shows the panel-started agent's log on demand.
The Monitoring tab is not shown on Signals Cloud, where Nightwatch is provisioned by the platform.
Related
- Security — SSO enforcement by role
- AI embeddings & configuration
- Document portal & payments — Stripe checkout rail
For record synchronisation over REST, see Integration identities for external references and provider mappings.