All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Mandate Gatekeeping: Tenant Access Control

Mandate Gatekeeping: Tenant Access Control

Overview

The Mandate Gatekeeping Status API lets any authorised consumer query whether a specific tenant should be granted or restricted access to downstream systems, based on the current state of their Direct Debit mandate.

This is the recommended integration point for applications like agentOS that need to enforce access control based on a tenant's payment mandate health.

How It Works

  1. The consuming application identifies a tenant by their email address or external reference.
  2. It calls the gatekeeping status endpoint (authenticated with an API key).
  3. The response contains the mandate status, the last collection outcome, and a pre-computed access_allowed boolean.
  4. The consuming application uses access_allowed to grant or restrict access (e.g. to a tenant portal).
  5. Optionally, the application subscribes to the status change webhook to receive push notifications when the status transitions, avoiding the need to poll continuously.

Mandate Statuses

StatusMeaning
activeMandate is in good standing; collections are running normally
suspendedMandate has been temporarily suspended; no collections are being taken
cancelledMandate has been cancelled; no further collections will occur
failedThe most recent collection or mandate registration failed

The access_allowed Flag

The access_allowed boolean abstracts the access control decision away from the consumer. It is computed by the service based on the mandate status and the last collection outcome, so the consuming application does not need to implement its own status-to-access mapping logic.

  • true — the tenant has an active, healthy mandate; access should be granted
  • false — the mandate is suspended, cancelled, or failed; access should be restricted

Webhook Events

When a tenant's gatekeeping status changes, the service fires a webhook event. This allows consumers to react immediately to transitions without relying on polling.

Example trigger scenarios:

  • A mandate is cancelled → access_allowed transitions to false → webhook fires
  • A tenant sets up a new mandate that becomes active → access_allowed transitions to true → webhook fires
  • A collection fails → last_collection_status updates → webhook fires

See the API Reference for webhook payload details.

Authentication

All requests to the gatekeeping status endpoint must be authenticated using an API key passed in the request header. API keys are scoped per customer (letting agent) and only return data for tenants within that customer's account.

Example Use Case

A letting agent uses agentOS to manage their tenant portal. When a tenant attempts to log in:

  1. agentOS calls the gatekeeping status endpoint with the tenant's email.
  2. The response returns access_allowed: false because the tenant's mandate was cancelled.
  3. agentOS blocks the login and displays a message prompting the tenant to set up a new Direct Debit mandate.
  4. Once the tenant completes a new mandate setup and it becomes active, the webhook fires and agentOS automatically restores portal access.