All Docs
Getting StartedagentOS Direct DebitUpdated March 13, 2026

Blog: Headless Integration — API Keys for External Consumers

Headless Integration — API Keys for External Consumers

v1.0.19 | API Authentication for External Consumers

The DD service has always been designed as a standalone, API-first system. With v1.0.19, that promise is fully delivered for machine-to-machine integrations. External services — starting with agentOS — can now call every DD procedure using a Bearer token API key, no user session required.

The Problem

Before this release, the DD service API was accessible only to authenticated user sessions. That worked well for the admin UI, but it was a blocker for server-to-server integrations. agentOS needs to trigger mandate invites, check collection statuses, and pull reports from its own backend — without a human sitting at a browser.

What Changed

We've extended the existing API key system with six DD-specific scopes and wired Bearer token authentication into the public endpoint layer:

mandates:read    — view mandate records and status
mandates:write   — create, cancel, suspend, reactivate mandates
collections:read — view collection schedules and history
alerts:read      — view threshold alerts
alerts:write     — acknowledge and dismiss alerts
reports:read     — pull success rate and clawback reports

Any request that previously required a session cookie can now be made with:

Authorization: Bearer <api-key>

Session auth still works exactly as before — this is purely additive.

Scope-Based Access Control

Keys are issued with explicit scopes. An integration that only needs to read mandate status gets mandates:read. An integration driving the full lifecycle gets all six. This means you can issue narrow keys to third-party consumers and retain full control over what each key can do.

Rate Limiting

To protect the service under load, API key requests are now rate-limited per organisation. If an integration sends too many requests in a short window it will receive a 429 Too Many Requests response. Build in back-off and retry logic — it's good practice regardless.

What This Unlocks

  • agentOS backend → DD service: Send mandate invites, poll collection status, forward alerts to the property management UI — all from agentOS server-side code.
  • Automation & scripting: Cron jobs or event-driven workflows can interact with the DD service without human login.
  • Future consumers: Any SaaS product that needs to embed DD collection can integrate via API key with no dependency on the DD service's session infrastructure.

Getting Started

  1. Issue an API key for your organisation with the required scopes.
  2. Store the key securely in your server environment (never in client-side code).
  3. Add Authorization: Bearer <your-api-key> to every request.
  4. Implement 429 handling with exponential back-off.

See the API Key Authentication page for full scope reference and security guidance.