API Key Authentication for External Consumers
API Key Authentication for External Consumers
Available from: v1.0.19
The Direct Debit service exposes a public endpoint layer that accepts API key authentication, allowing external systems such as agentOS to integrate with all DD procedures without requiring a user session. Access is controlled through fine-grained scopes assigned to each API key.
Authentication
Authenticate API key requests by passing the key as a Bearer token in the Authorization header:
Authorization: Bearer <your-api-key>
Bearer token authentication is accepted alongside existing session-based authentication. Both mechanisms are valid on all DD endpoints.
Scopes
Each API key is issued with one or more scopes that control what it can access. Requests made with a key that lacks the required scope for an operation will be rejected.
| Scope | Permitted Operations |
|---|---|
mandates:read | Read mandate records, status, and details |
mandates:write | Create, update, cancel, suspend, and reactivate mandates |
collections:read | Read collection schedules, history, and status |
alerts:read | Read threshold alerts and notifications |
alerts:write | Acknowledge and manage alerts |
reports:read | Access collection reports, success rates, and clawback history |
Assign only the scopes an integration needs — follow the principle of least privilege.
Example: Read-only integration
An integration that only needs to display mandate and collection status should be issued a key with:
mandates:read
collections:read
Example: Full agentOS integration
An integration that drives the full DD lifecycle — sending mandate invites, cancelling mandates, acknowledging alerts, and pulling reports — should be issued a key with all six scopes:
mandates:read
mandates:write
collections:read
alerts:read
alerts:write
reports:read
Rate Limiting
API key requests are rate-limited on a per-organisation basis. If your integration exceeds the rate limit, the API will respond with:
HTTP 429 Too Many Requests
Implement exponential back-off and retry logic in your integration to handle rate limit responses gracefully.
Multi-Tenancy & Data Isolation
API keys are scoped to a single organisation. A key issued for one letting agent cannot access data belonging to another. All requests authenticated via API key are automatically scoped to the issuing organisation — no additional tenant identifier is required in the request.
Security Considerations
- Store API keys securely — treat them as secrets equivalent to passwords.
- Rotate keys regularly and immediately if you suspect a compromise.
- Use the narrowest set of scopes necessary for each integration.
- Do not embed API keys in client-side code or public repositories.
- Per-org rate limiting is enforced server-side; do not rely on it as the sole safeguard against runaway integrations.