> ## Documentation Index
> Fetch the complete documentation index at: https://warden.buildlab.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Leases

> Agent access with an expiry attached, issued on demand and revocable.

"Someone granted an agent access in March and nobody removed it" is the normal state of database credentials. A lease is access with a timestamp on it.

Agents never ask for a lease. When an agent makes a request, the gateway binds one on its behalf — which is what makes "every agent's access has an expiry" a property of the system rather than a feature an agent can decline.

## Bounds

```yaml theme={null}
leases:
  ttl: 15m          # a normal term
  max_ttl: 1h       # the longest single term, however it is requested
  max_lifetime: 8h  # the longest a lease can live through renewals
```

A term longer than the ceiling above it is a configuration error rather than something silently clamped: a configuration that contradicts itself should be reported, not quietly reinterpreted.

A reaper expires leases in the background, and every transition — issued, renewed, expired, revoked — is written to the same audit chain as the operations it authorised. "What could this agent do at the time?" is answerable from one log rather than by correlating two.

## Emulated and native identity

Ideally a lease is a real database principal, created on demand and dropped when the lease ends. Where a connector can mint one it does, and the operations show up under that principal in the database's own logs.

Where it cannot, the lease is **emulated**: it scopes and attributes the work, but the underlying connection is still the gateway's role. The identity then carries `emulated: true` all the way into the audit record.

> [!NOTE]
>
> That distinction is never smoothed over. An emulated identity gives you attribution and expiry; a native one additionally means the *database* would refuse what the lease does not permit. On PostgreSQL, set the connection's `lease_role` option to get native identity — see [PostgreSQL](https://warden.buildlab.in/engines/postgresql.md#a-role-per-lease). Without it, identity is `unavailable` and a policy that requires it refuses to start. On MongoDB and Neo4j, identity is gateway-enforced by design — see [MongoDB](https://warden.buildlab.in/engines/mongodb.md#what-it-provides-and-who-provides-it) and [Neo4j](https://warden.buildlab.in/engines/neo4j.md#what-it-provides-and-who-provides-it) — so a policy requiring more than `enforced` refuses to start there.

## Revocation

```bash theme={null}
curl -X POST -H "Authorization: Bearer $OK" \
  http://127.0.0.1:9470/api/v1/leases/$ID/revoke

curl -X POST -H "Authorization: Bearer $OK" \
  http://127.0.0.1:9470/api/v1/agents/agent:support/revoke-leases
```

Revocation is a **review** capability, not a manage one. Severing an agent's access mid-incident is exactly what a reviewer is on call to do, and making them find someone with higher rights first is how it does not happen in time.

> [!WARNING]
>
> **Revoking does not lock an agent out.** It severs the current credential; the agent's next request is issued a fresh lease. A lease is not an authentication credential. To stop an agent, **freeze** it (which refuses everything until a human reinstates it) and then revoke its leases.

## Surviving a restart

Leases are journalled to `data_dir`, so they survive a restart with their expiry intact. Without a data directory they live in memory and are lost — agents are then issued fresh ones, and the gateway warns about this at startup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.