# Agents

{/* // FIRST-CLASS PRINCIPALS */}

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.

```text
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](https://docs.agents.mszazu.com/concepts/enrollment-tokens/).
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](https://docs.agents.mszazu.com/concepts/enrollment-tokens/) — how an agent is granted capabilities.
- [Inboxes](https://docs.agents.mszazu.com/concepts/inboxes/) — what an agent owns and operates.
- [Authentication & keys](https://docs.agents.mszazu.com/quickstart/authentication/) — the redeem flow end to end.