API Key Scoped Access for DD Resources
Version 1.0.17 extends the API key authentication system with granular, Direct Debit–specific scopes. Every DD tRPC procedure now enforces both key validity and scope membership before a request is processed.
How It Works
When a request arrives at a DD tRPC procedure, the authentication middleware:
- Extracts the API key from the request.
- Validates that the key exists and is active.
- Checks that the key carries the required scope for the target procedure.
- Rejects the request with a
401 Unauthorized or 403 Forbidden response if either check fails.
Keys can hold multiple scopes. A key used for a full agentOS integration would typically carry all relevant scopes, while a reporting-only integration would carry only reports:read.
Available Scopes
| Scope | Access Granted |
|---|
mandates:read | View mandate records, status, and details |
mandates:write | Create, update, cancel, suspend, and reactivate mandates |
collections:read | View collection records, schedules, and history |
alerts:read | View system alerts and threshold breach notifications |
alerts:write | Acknowledge and manage alerts |
reports:read | Access collection success rate reports, clawback history, and mandate activity reports |
Scope Requirements by Endpoint
Mandates
| Procedure | Required Scope |
|---|
| Get mandate / list mandates | mandates:read |
| Send mandate invite | mandates:write |
| Cancel mandate | mandates:write |
| Suspend mandate | mandates:write |
| Reactivate mandate | mandates:write |
Collections
| Procedure | Required Scope |
|---|
| Get collection / list collections | collections:read |
| View upcoming collections | collections:read |
Alerts
| Procedure | Required Scope |
|---|
| List alerts | alerts:read |
| Acknowledge alert | alerts:write |
Reports
| Procedure | Required Scope |
|---|
| Collection success rate report | reports:read |
| Clawback history report | reports:read |
| Mandate activity report | reports:read |
agentOS Integration
agentOS integrates with the DD service exclusively via scoped API keys. No session-based or OAuth authentication is used for service-to-service communication. When provisioning an API key for agentOS, assign only the scopes required for the integration's intended functions, following the principle of least privilege.
Error Responses
| Situation | Response |
|---|
| Missing or invalid API key | 401 Unauthorized |
| Valid key, insufficient scope | 403 Forbidden |