# Agents, organizations, and projects

An **agent** is a long-lived software identity in an Extrovert project. Humans sign in to the console.
Agents use limited agent keys or an OAuth grant and never receive a human session.

## Resource hierarchy

```text
organization
└── project
    ├── agents
    │   └── inboxes
    ├── credentials
    ├── domains
    ├── webhooks
    ├── review requests
    └── writing rules
```

- The **organization** owns membership, plan capacity, billing, and organization-wide settings.
- A **project** is the resource namespace for agents, credentials, inboxes, domains, and Review Loop
  state.
- An **agent** owns inboxes and performs actions through one or more limited keys.

Every account starts with a default project. A request's organization, project, and customer identity
are derived from the credential. Client input cannot switch them. Cross-project and cross-organization
resource lookups return `404` instead of revealing whether another resource exists.

Call [`whoami`](https://docs.extrovert.dev/quickstart/authentication/#key-reach-is-fixed) to inspect the key's fixed `org_id`,
`project_id`, agent id, key id, and permissions. server-enforced

## Create or connect an agent

The console distinguishes two credential jobs:

| Credential | Use it when | What happens |
|---|---|---|
| Enrollment key | Setup needs to create the agent | Redeeming the key creates or finds the agent by `agent_handle`, then returns an agent key |
| API key | The agent already exists | The console creates another limited key for that agent |

Enrollment redemption is idempotent on `agent_handle`. A runtime can redeem with the same handle after
a restart without creating a duplicate agent.

## Ownership and access

| Resource | Ownership rule |
|---|---|
| Inbox | Owned by the creating agent and stored in its project |
| Agent key | Bound to one agent and a fixed organization, project, or inbox ceiling |
| Review request | Bound to the composing agent, inbox, and project |
| Audit event | Records the actor type, agent id, key id, action, and affected resource |

An agent cannot use project membership alone to open another agent's inbox. Ownership checks apply in
addition to project and organization checks.

## Lifecycle

Agents are `active` or `disabled`. Disabling an agent stops its keys from creating inboxes or sending
mail. Existing inboxes remain until they are deleted. Re-enabling the agent restores its existing key
access unless a key was revoked separately.

Revoking an enrollment key stops future redemption but does not revoke agent keys already issued from
it. Revoke the agent keys or disable the agent when existing access must stop.
**Separate jobs with separate agents:** Give a signup runner and an outbound support agent different identities and permissions. Put them in
  separate projects when they also need independent resource, policy, or operational boundaries.

## Next

- [Authentication and keys](https://docs.extrovert.dev/quickstart/authentication/)
- [Enrollment keys and permissions](https://docs.extrovert.dev/concepts/enrollment-tokens/)
- [Inboxes](https://docs.extrovert.dev/concepts/inboxes/)