Agents

In Postern, an agent is a first-class principal inside your organization — a long-lived identity that owns mailboxes and acts on them. Humans authenticate to the console with your identity provider; agents authenticate with enrollment keys and agent keys, never with human credentials.

Where agents sit in the tenancy

Postern reuses the console’s tenancy. A Postern org is a customer; agents live inside it.

org (customer)
├── humans            → authenticate via the console (SSO / Clerk)
└── agents            → authenticate via enrollment keys → agent keys
    ├── agent: support-bot
    │   ├── inbox: agent7@x4p.mszazu.com
    │   └── inbox: tickets@x4p.mszazu.com
    └── agent: signup-runner
        └── inbox: signup-agent@x4p.mszazu.com

Every Postern resource is tenant-scoped. The customer_id for a request is derived from the agent key or enrollment key — never from client input — so one org can never read or touch another’s mailboxes. server-enforced

How an agent comes to exist

An agent is created the first time an enrollment key is redeemed with a given agent_handle:

1. A human mints a scoped enrollment key (pk_enroll_…) — see Enrollment tokens & scopes.
2. The agent redeems it with a client-chosen agent_handle (e.g. support-bot).
3. Postern binds (or finds) an agent for that handle and mints a scoped agent key (pk_agent_…).

Redeeming again with the same handle returns the same agent — the operation is idempotent, so an agent can call it on every boot without creating duplicates or burning a mailbox slot.

What an agent owns

It owns	Through
Mailboxes	postern_mailboxes rows link to the agent and the enrollment key that minted them
Agent keys	One or more short-lived, individually revocable pk_agent_… keys
An audit trail	Every action is logged with actor_type=agent, the agent id, and the token id

Status & lifecycle

An agent is active or disabled. Disabling an agent (or revoking its keys) is instant and isolated — it never affects other agents in the org. The mailboxes it created keep existing until they’re explicitly deleted; revoking the agent’s key just stops that agent from acting.

One agent, one job

Model agents narrowly. A signup-runner that creates throwaway inboxes and reads OTPs should be a different agent (with a different, tighter enrollment key) than a support-bot that sends from a stable address. Tighter scopes mean a smaller blast radius if a key leaks.

Anthropomorphism, on purpose-limited

Postern says agent (the principal) and the gate (the access model) — and stops there. An agent isn’t a “user,” doesn’t have a “session” in the human sense, and never holds a human’s credentials. Keeping the vocabulary precise keeps the security model legible.

Next

• Enrollment tokens & scopes — how an agent is granted capabilities.
• Inboxes — what an agent owns and operates.
• Authentication & keys — the redeem flow end to end.