All Docs
Getting StartedagentOS Direct DebitUpdated March 13, 2026

What's New in v1.0.17: API Key Scoped Access for DD Resources

What's New in v1.0.17: API Key Scoped Access for DD Resources

Version 1.0.17 ships granular, scope-based access control on top of the existing API key system. Every Direct Debit tRPC procedure now declares the exact scope a key must hold before the request is processed.

The Problem This Solves

Before this release, an API key granted broad access to the DD service. That's fine for early development, but it creates unnecessary risk in production: a compromised key or an overly permissive integration could read or modify resources it should never touch.

With scoped keys, you can issue a key that can only read reports, or only send mandate invites — nothing more.

Six New Scopes

The following scopes are now available when provisioning an API key:

  • mandates:read — read-only access to mandate data
  • mandates:write — full mandate lifecycle management (create, cancel, suspend, reactivate)
  • collections:read — view collection records and upcoming schedule
  • alerts:read — view threshold alerts and system notifications
  • alerts:write — acknowledge and manage alerts
  • reports:read — pull collection, clawback, and mandate activity reports

How the Middleware Works

Every DD tRPC procedure is wrapped by authentication middleware that runs two checks in sequence:

  1. Key validation — is this a known, active key?
  2. Scope check — does this key carry the scope required by the procedure being called?

If either check fails, the request is rejected before any business logic runs. There is no way to bypass scope enforcement from the API layer.

What This Means for agentOS

agentOS is the primary consumer of the DD service and integrates exclusively via scoped API keys. This release standardises that integration pattern: agentOS keys are provisioned with precisely the scopes needed, and the middleware enforces those boundaries on every request.

If you are building a custom integration, follow the same pattern — request only the scopes your integration needs.

Further Reading