LAYER 1 · AGENT IDENTITY
Identity reference Endpoints, fields, token claims, errors, and configuration for the identity surface. For the full API, see the API reference.
Overview How it works Guides Reference Method Path Min role Purpose Returns POST /agentsdeveloper Register an agent; mints its token in the same transaction. 201 — {agent, token}; the token appears here onlyGET /agentsviewer List your org's agents. Filters: environment, risk_level, status, owner; limit (default 50, max 200), offset. Array of agent records, newest first GET /agents/{id}viewer Fetch one agent record. The agent record PATCH /agents/{id}developer Update mutable fields. status is deliberately not accepted — state changes go through the lifecycle endpoints only. The updated agent record POST /agents/{id}/rotatedeveloper Revoke every live token for the agent and mint a replacement. {agent, token}; the new token appears here onlyGET /cimd/{agent_id}.jsonnone (public) The agent's public identity document for MCP servers resolving callers. Metadata only, no secrets. client_id, client_name, and a sentnelops identity block
Field Type Set by Mutable? idUUID server, at registration no namestring you, at registration no ownerstring you, at registration yes — PATCH environmentproduction | staging | dev you, at registration no risk_levellow | medium | high you (default medium) yes — PATCH allowed_mcpstring[] you (default []) yes — PATCH; frozen while suspended denied_mcpstring[] you (default []) yes — PATCH; frozen while suspended statusdraft | approved | active | suspended | decommissioned server (from environment) only via lifecycle endpoints created_bystring you, at registration no approved_bystring | null server, on approval no org_idUUID server, from your credential no created_at / updated_attimestamp server no / advances on change expires_attimestamp | null you yes — PATCH last_review / next_reviewtimestamp | null server, on review via the review endpoint suspended_at / suspend_reasontimestamp | string | null server, on suspension no
HS256 JWT, self-contained, no exp — revocation happens in the database, not by expiry.
Claim Meaning subThe agent id (UUID). Everything else keys off this. nameAgent name at issuance. ownerOwner at issuance. environmentThe agent's environment at issuance. risk_levelRisk level at issuance. allowed_mcpAllowed MCP servers at issuance. A snapshot — the policy engine reads the live record, not this claim. issIssuer, verified on decode. Default sentnelops.com. iatIssued-at, Unix seconds. jtiRandom nonce (8 bytes hex) making every issuance a distinct token — so rotation can never revoke the token it just minted.
Status When What it looks like 401Missing or invalid bearer credential; at the proxy, also a revoked token. missing bearer credential, invalid api key, revoked agent token403Your role is below the endpoint's minimum. requires the developer role (you are viewer)404Agent not found — including agents that exist in another org, and unknown or malformed CIMD ids. agent not found409The record's state forbids the change. terminal_state (decommissioned), scope_frozen (scope PATCH while suspended)422Body validation failed — e.g. an environment or risk level outside the allowed values. FastAPI validation detail listing the offending fields 429Per-credential rate limit exceeded. Includes a Retry-After header
Setting Default Effect SNOPS_JWT_SECRETdev placeholder — change it Signs both agent tokens and user sessions. Rotating it invalidates every token and session at once. SNOPS_PROXY_IDENTITY_TTL_SECONDS5.0 How long the proxy caches identity resolution and revocation checks. The staleness bound on revocation: a just-revoked token survives at most this long. 0 disables the cache.
Lifecycle transitions, approvals, and review cadence live in Layer 2 — Lifecycle & policy . For registering step by step, go back to the guides .
SentnelOps