Skip to main content

​
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, which is the IdP-driven half of the same lifecycle.
This page documents a tenant-owned control, per Orbit’s compliance model. Whether your organization needs an NHI inventory depends on your policy and your counsel. Orbit documents the control; you own the decision.

​
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.
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):

​
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. 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.

​
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:
  • 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:

​
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.