# Enrollment keys and permissions

An enrollment key is a bootstrap credential for software that needs to create its agent identity. It
does not grant organization-wide access. The key is bound to a project and carries explicit
permissions and limits.

## Issue an enrollment key

In the console, open **Credentials > Enrollment keys** and select **Issue enrollment key**. Choose:

| Setting | Meaning |
|---|---|
| Label | Identifies the installer, environment, or agent that receives the key |
| Permission preset | Starts with a practical permission set; custom permissions remain available |
| Expiration | Stops new redemptions after the selected time |
| Redemptions | Single-use for one agent, or reusable for multiple agents |
| Maximum inboxes | Lifetime number of inboxes created through this enrollment key |
| Daily send limit | Per-inbox rolling 24-hour recipient cap inherited by issued agent keys; `0` uses the organization default |
| Allowed domains | Restricts inbox creation and domain operations to selected eligible domains |

The raw `pk_enroll_…` value is shown once. Extrovert stores only a hash.

## Redemption and use

1. **Issue.** A human chooses the project's permissions and limits.
   console

2. **Redeem.** The runtime calls `POST /v1/enroll` with the key and a stable `agent_handle`.
   Extrovert creates or finds that agent and returns a project-bound `pk_agent_…` key.

3. **Create inboxes.** Each successful create increments the server-side `used_count`. A copied key
   cannot exceed its lifetime `max_mailboxes` value.

4. **Revoke.** Revoking the enrollment key stops future redemption. Revoke an existing agent key or
   disable its agent to stop access that was already issued.

## Permissions

The product term is **inbox**. The existing `mailbox:*` names remain on the wire for compatibility.

| Permission | Allows |
|---|---|
| `mailbox:create` | Create inboxes and perform owning-agent lifecycle cleanup |
| `mailbox:read` | Read inboxes, messages, threads, rules, review events, suppressions, and contact lists |
| `mailbox:send` | Submit send, reply, forward, review chat, and revision requests |
| `mailbox:delete` | Permanently delete inboxes |
| `mailbox:credentials` | Export portable IMAP and SMTP credentials on an eligible paid plan |
| `mailbox:quota` | Change an inbox's effective daily recipient limit |
| `webhook:write` | Create, update, and delete webhooks |
| `domain:manage` | Onboard, verify, inspect, and offboard customer-controlled domains |
| `commerce:request` | Quote and request domain purchases or plan changes; never approve spending |
| `review:act` | Act on a Review Loop request when an active reviewer link also authorizes it |

Permissions are additive. The returned agent key cannot exceed the enrollment key's set.

## Limits are checked by the server

The project binding, expiration, allowed domains, lifetime inbox count, and permissions are checked on
every relevant request. A leaked key cannot bypass them by changing client input.

Deleting an inbox does not refund a lifetime creation slot. The non-refunding counter limits the damage
from a copied bootstrap key. Project plan capacity is separate and can stop creation before the
enrollment key reaches its own limit.
**The key alone is not the whole policy:** Review policy, suppression, contact lists, plan capacity, purchase limits, and daily send accounting
  apply independently. A permission allows an operation to be attempted; it does not bypass those
  controls.

## Next

- [Authentication and keys](https://docs.extrovert.dev/quickstart/authentication/)
- [Agents, organizations, and projects](https://docs.extrovert.dev/concepts/agents/)
- [Rate limits and quotas](https://docs.extrovert.dev/operating/limits/)