> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Identity Governance: NHI Inventory + Bulk Decommission

> Tenant-owned inventory of every AI-agent non-human identity — lifecycle status, human-sponsor attribution, per-channel reach — plus a reversible bulk-suspend endpoint for estate-wide decommission.

# Agent Identity Governance: Inventory and Bulk Decommission

Every AI agent you create in Orbit is a non-human identity (NHI): a
workload identity with its own lifecycle status, its own human sponsor,
and per-channel limits on what it can reach. The Cloud Security
Alliance's NHI framework expects a security team to answer four
questions on demand: which agents exist, who sponsors each one, what
can each one touch, and can you stop them all right now.

Agent identity governance gives you those answers on a
session-authenticated surface, per organization — no IdP round-trip
required. It complements the [SCIM Agents resource](/compliance/scim-provisioning),
which is the IdP-driven half of the same lifecycle.

<Warning>
  This page documents a tenant-owned control, per Orbit's
  [compliance model](/compliance/posture-overview). Whether your
  organization needs an NHI inventory depends on your policy and your
  counsel. Orbit documents the control; you own the decision.
</Warning>

## Auditing agent identities (per-organization)

All inventory and decommission data is scoped to your organization —
its own tenant schema, its own agents, its own roster. You always see
only your agents and your own member roster, never another
organization's, and the two base queries below are double-clamped on
`organization_id` and the agent's `id`, so an id you do not own can
never be returned.

```bash theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/settings/agent-identities" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

Both inventory and bulk-suspend are guarded by the `agents:read` /
`agents:write` scope and the **owner/admin role** — decommissioning
an identity estate is never a self-service or read-only action.

## Inventory columns

`GET /settings/agent-identities` returns one row per agent, paged
(`page`, `pageSize`, `status`, `sponsorId`, `search` query filters):

| Column                   | Meaning                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`                     | Agent identity id (opaque).                                                                                                    |
| `name`, `description`    | The display name and free-text description you set.                                                                            |
| `type`                   | Agent type (the variant of agent).                                                                                             |
| `status`                 | Lifecycle status — see below.                                                                                                  |
| `active`                 | Boolean projection identical to the SCIM `active` flag: `true` unless `status` is `suspended`.                                 |
| `sponsor`                | The human sponsor — resolved to `{ id, name, email }` from your org's member roster, or `null` if the member has been removed. |
| `createdAt`, `updatedAt` | Creation and last-modified timestamps.                                                                                         |
| `channelCaps`            | Per-channel concurrency caps — the agents-capped limits on what this agent can reach right now (`channel` + `maxConcurrent`).  |

### Lifecycle status

* `draft` — created but not yet in service.
* `active` — in service; routed traffic reaches the agent.
* `suspended` — decommissioned. The agent no longer receives
  traffic, but nothing is deleted and history is preserved. `active`
  projects to `false`, matching the SCIM suspend mapping.

The same inventory is paginated from the same agents table the SCIM
`/Agents` resource lists — so a dashboard pull and an IdP pull agree
on the estate.

## Sponsor attribution

Every agent row carries the identity of the human who created it
(the sponsor, recorded at creation time) plus the audit trail from
the authorization-mandate routes — every mandate issue, act, and
revoke is audit-logged with the acting principal's id. The inventory
resolves the sponsor id to a name and email from your organization's
member roster. If the sponsor has left the roster, the id is still
returned and the name/email resolve to nothing — the attribution
stays intact after off-boarding.

For the mandate-level scope, expiry, and principal audit detail, see
[authorization mandates](/agents/authorization-mandates).

## Bulk suspend (the decommission endpoint)

`POST /settings/agent-identities/bulk-suspend` suspends one or many agents in
a single call — reversible by design, never a delete:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/settings/agent-identities/bulk-suspend" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["agent-abc123", "agent-def456"] }'
```

* **Reversible, never a delete.** A suspended agent keeps its call
  recordings, conversation history, and spend attribution intact; the
  suspension is what an access review expects to undo.
* **Bounded.** Up to 500 explicit `ids` per request, or
  `{ "all": true }` to target the whole inventory at once.
* **Idempotent.** Re-suspending an already-suspended agent is a
  no-op; the response is stable under re-runs.
* **Auditable, per id.** Any id your organization does not own — or
  that does not exist — is reported back in `notFound` instead of
  silently dropped, so a mis-targeted revoke is visible in the
  response alone. Every suspend is written to the org audit log.

To decommission the full estate at once:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/settings/agent-identities/bulk-suspend" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "all": true }'
```

## Step by step

1. **Enumerate.** `GET /settings/agent-identities` and page through
   the inventory; filter by `status`, `sponsorId`, or a `search`
   substring to narrow to the estate you are auditing.
2. **Review sponsors.** For each row, confirm the `sponsor` is still
   an active member of your organization and that the agent's
   `channelCaps` match what the sponsor intended it to reach.
3. **Suspend the selection.** Collect the ids you are decommissioning
   and `POST /bulk-suspend` with the `ids` list (or `all: true`).
   Check `notFound` in the response — any id your org did not own
   comes back there.
4. **Optionally restore.** Suspension is reversible: reactivate the
   agent through the same agent surface you use to manage it, and
   the agent returns to service with its history intact.

## Related

* [Agent governance policies](/agents/agent-governance-policies) —
  mandate scopes, expiry, and guardrails on top of the identity.
* [SCIM provisioning](/compliance/scim-provisioning) — the IdP-facing
  half of the same NHI lifecycle.
* [Authorization mandates](/agents/authorization-mandates) — how
  agents act under a scoped, expiring mandate.