Use Case 025: Agent Identity Registration & Lifecycle

Overview

Implementation status (agent-identity release, June 2026). Shipping on development. The tenant-owned agent registry (AgentIdentity), scope ceiling, allowed task-types, per-turn budget, public-key registry, and disable/revoke lifecycle exist end-to-end (Web /agents, API /api/agents) with integration tests. Canonical code names differ from parts of this original spec — the real types are AgentIdentity, RegisterAgentCommand / UpdateAgentCommand, and IAgentRepository; scope and task-type lists persist as space-delimited strings.

Description

This use case describes how an owner/admin registers, configures, and manages the lifecycle of a non-human agent identity (an AI agent or automated process) in Application Manager. Each agent is a tenant-owned, first-class identity with a required human owner for accountability, a link to the registered application(s) that bound its scope ceiling, a set of allowed task types, governance limits, and registered public keys used for keyless private_key_jwt authentication. Agents minted from this registry receive scoped, ephemeral credentials (UC-026) and may delegate on behalf of subjects (UC-027). The registry is the upper bound for everything an agent can ever do: no credential, token, or delegation may exceed the agent's scope ceiling or governance limits.

This is part of the agent-identity release. The SDK master design is riptide-sdk/docs/plans/AGENT-IDENTITY-ARCHITECTURE.md; the Application Manager-side plan is docs/internal/agent-identity-plan.md (Section 1, plus the identity items in §9 Reuse and §10 Resolved decisions). The AgentIdentity lifecycle shape (ExpiresAt/RevokedAt/RevokedReason/IsActiveAt(moment)) and the AgentPublicKey substrate (ECDSA P-256, kid rotation, validity windows, revocation) are lifted from the existing SyntheticPrincipal and AttestationPublicKey patterns — reused, not rebuilt.

Actors

Preconditions

1. Application Manager is running and reachable on the Web (11401) and API (11402) ports.
2. The acting owner/admin is authenticated and holds the agents.read and agents.write capabilities.
3. The owning tenant exists and is Active or Trial.
4. At least one registered application exists to bind the agent's scope ceiling.
5. A Top-tier budget cap exists for the tenant with viable headroom (UC-032); agent creation is fail-closed without it.
6. The owner has (or will register) at least one ECDSA P-256 public key for the agent.

Postconditions

Success Postconditions

1. An AgentIdentity row is persisted in IdentityDbContext with status Active, a required OwnerUserId, bound application link(s), scope ceiling, AllowedTaskTypes + DefaultTaskType, PerTurnBudget, governance limits, and audit fields.
2. One or more AgentPublicKey rows are persisted with kid, validity window, and Active state.
3. The agent appears in the registry list and is resolvable by GetAgentById.
4. An audit entry recording the actor chain is written to AuditLog.

Failure Postconditions

1. No AgentIdentity row is created when validation fails (missing owner, no app link, no budget headroom, requested ceiling outside the bound application's grantable scopes).
2. A descriptive error (RFC 7807 Problem Details on the API; validation summary in the Web UI) is returned.
3. No partial state: public keys are not orphaned if the agent insert is rolled back.

Primary Flow Sequence

sequenceDiagram
    participant Admin as Owner/Admin
    participant Web as AM Web (AgentsController)
    participant Med as MediatR
    participant Gov as Cost Governance
    participant Repo as IAgentRepository
    participant DB as IdentityDbContext
    participant Audit as AuditLog

    Admin->>Web: Submit "Register Agent" form
    Web->>Med: Send RegisterAgentCommand
    Med->>Med: FluentValidation (owner, app link, ceiling ⊆ app scopes)
    Med->>Gov: Check viable budget headroom (UC-032)
    Gov-->>Med: Headroom OK
    Med->>Repo: Add AgentIdentity (status=Active)
    Repo->>DB: INSERT AgentIdentity + AgentPublicKey
    DB-->>Repo: Saved
    Med->>Audit: Write actor-chain entry (agent.registered)
    Med-->>Web: AgentDto (Id, status, ceiling)
    Web-->>Admin: Redirect to agent detail page (success toast)

UC-025a: Register Agent

Triggers

• Owner/admin navigates to /agents/create in the Web UI, or
• An SDK consumer calls POST /api/agents.

Basic Flow

1. Owner/admin opens Agents > Register Agent.
2. System displays the registration form: name, owner (defaults to the acting admin), one or more bound applications, scope ceiling builder, task-type selection, PerTurnBudget, optional TemplateId, governance limits (max credential TTL, allowed MCP servers, reservation rate-cap override, reservation count-cap override), optional ExpiresAt, and a public-key upload field.
3. Owner/admin sets the scope ceiling — the two-axis set (coarse {app}:{action} capabilities + fine-grained mcp:{server}:{tool} tool scopes) that bounds every credential the agent can ever mint. The ceiling must be a subset of the scopes grantable by the bound application(s).
4. Owner/admin sets AllowedTaskTypes and DefaultTaskType. Two provisioning UX paths produce this (purpose-picker or direct-model-picker); both set AllowedTaskTypes/DefaultTaskType (detail in UC-029).
5. Owner/admin pastes/uploads at least one ECDSA P-256 public key; the system assigns a kid and validity window.
6. System validates: owner present, at least one app link, ceiling ⊆ app grantable scopes, task types valid, governance limits within tenant policy, public key well-formed.
7. System checks budget headroom via the cost-governance subsystem (UC-032). Registration is blocked with a clear error if no viable budget headroom exists.
8. System persists the AgentIdentity (status Active) and AgentPublicKey row(s) in one transaction.
9. System writes an AuditLog entry (agent.registered) with the actor chain.
10. System redirects to the agent detail page with a success message.

Alternative Flows

• A1: Missing owner — Validation rejects; required OwnerUserId enforced for accountability.
• A2: No application link — Validation rejects; ceiling cannot be bound without a registered application.
• A3: Ceiling exceeds app scopes — Validation rejects requested scope ceiling that is not a subset of the bound application's grantable scopes.
• A4: No budget headroom — Cost governance blocks creation; admin is directed to set/raise a cap (UC-032).
• A5: Malformed public key — Key rejected; agent not created (or created without key if API allows deferred key registration, depending on policy).
• A6: Duplicate name within tenant — Validation rejects to keep the registry unambiguous.

UC-025b: View / List Agents

Triggers

• Owner/admin navigates to /agents, or calls GET /api/agents.
• Owner/admin opens an agent detail page, or calls GET /api/agents/{id}.

Basic Flow

1. Owner/admin clicks Agents in the navigation bar.
2. System runs GetAgents scoped to the caller's tenant.
3. System renders a Tabler table: name, owner, bound application(s), status badge (Active/Disabled/Revoked/Expired), DefaultTaskType, active credential count, ExpiresAt, and an action dropdown.
4. Owner/admin selects an agent to view detail via GetAgentById.
5. The detail page shows: identity card (name, owner, tenant, status, lifecycle dates), scope ceiling, AllowedTaskTypes/DefaultTaskType, governance limits, registered public keys (with kid, validity window, state), and minted credential summary.

Alternative Flows

• A1: Agent not found — GetAgentById returns not found; API returns 404 Problem Details, Web shows an error.
• A2: Cross-tenant access — A caller from another tenant cannot see the agent; result is filtered as not found.
• A3: Status auto-derivation — An agent past its ExpiresAt displays as Expired via IsActiveAt(now) even if not yet swept.

UC-025c: Update Scope Ceiling & Allowed Task-Types / Deployments

Triggers

• Owner/admin edits an agent and submits scope-ceiling or task-type changes.

Basic Flow

1. Owner/admin opens Agents > > Edit.
2. Owner/admin modifies the scope ceiling and/or AllowedTaskTypes/DefaultTaskType and/or allowed deployment set.
3. For scope-ceiling changes, system sends UpdateAgentScopesCommand; for deployment/task-type changes, UpdateAllowedDeploymentsCommand.
4. System validates the new ceiling ⊆ bound application grantable scopes and that DefaultTaskType ∈ AllowedTaskTypes.
5. System persists the change and writes an AuditLog entry recording before/after values.
6. Already-issued credentials are unaffected at issue time but constrained by the new ceiling at introspection/refresh (the ceiling is the upper bound; tightening it narrows future mints — see UC-026).

Alternative Flows

• A1: New ceiling exceeds app scopes — Validation rejects; no change persisted.
• A2: DefaultTaskType not in AllowedTaskTypes — Validation rejects.
• A3: Removing a task type still referenced by active plans — Change allowed; active plans complete against prior config, new mints use the new set.

UC-025d: Disable Agent

Triggers

• Owner/admin clicks Disable on the list or detail page, or calls a disable action.

Basic Flow

1. Owner/admin confirms the disable action.
2. System sends DisableAgentCommand, setting status Disabled.
3. New credential minting and token issuance are refused while disabled; existing credentials remain valid until expiry unless separately revoked.
4. System writes an AuditLog entry.

Alternative Flows

• A1: Already disabled — Operation is idempotent; no error.
• A2: Re-enable — A disabled agent may be re-enabled (status back to Active) provided budget headroom still exists.

UC-025e: Revoke Agent

Triggers

• Owner/admin clicks Revoke on the list or detail page.

Basic Flow

1. Owner/admin confirms revocation (irreversible) and optionally provides a RevokedReason.
2. System sends RevokeAgentCommand, setting RevokedAt = now, RevokedReason, and status Revoked.
3. System cascades: all active AgentCredentials for the agent are invalidated and active delegation grants revoked (UC-026, UC-027).
4. IsActiveAt(moment) returns false for any moment ≥ RevokedAt; introspection on any minted credential returns inactive.
5. System writes an AuditLog entry with the RevokedReason.

Alternative Flows

• A1: Already revoked — Idempotent; no error.
• A2: Revoke during in-flight call — Outstanding credentials fail at the next introspection; mid-stream calls hard-stop per governance.

UC-025f: Per-Agent Audit View

Triggers

• Owner/admin opens Agents > > Audit, or calls GET /api/agents/{id}/audit.

Basic Flow

1. Owner/admin opens the per-agent audit view.
2. System runs GetAgentAudit filtering AuditLog to the agent.
3. System renders a chronological list of lifecycle and credential events: registration, scope changes, deployment-set changes, credential mints/revocations, delegation grants/exchanges/revocations, disable/revoke — each with the full actor chain (agent ⇽ on-behalf-of subject where applicable) and before/after values for config changes.

Alternative Flows

• A1: No events — Empty state shown.
• A2: Filter by event type / date range — Query supports narrowing the result set.

API Endpoints

Representative Example — POST /api/agents

Request:

{
  "name": "invoice-triage-agent",
  "ownerUserId": "0190f3a1-2b6c-7c44-9b1e-1f2a3b4c5d6e",
  "applicationIds": ["0190e2b0-1a2b-7c33-8a0d-9e8f7a6b5c4d"],
  "scopeCeiling": {
    "capabilities": ["billing:read", "billing:export"],
    "toolScopes": ["mcp:invoices:list", "mcp:invoices:fetch"]
  },
  "allowedTaskTypes": ["analysis.financial", "summarization.document"],
  "defaultTaskType": "analysis.financial",
  "perTurnBudget": { "amount": 0.50, "currency": "USD" },
  "templateId": "finance.triage",
  "governance": {
    "maxCredentialTtlSeconds": 900,
    "allowedMcpServers": ["invoices"],
    "reservationRateCapPerMin": 60,
    "reservationCountCap": 100
  },
  "expiresAt": "2026-12-31T23:59:59Z",
  "publicKeys": [
    {
      "kid": "key-2026-06",
      "alg": "ES256",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----",
      "notBefore": "2026-06-09T00:00:00Z",
      "notAfter": "2027-06-09T00:00:00Z"
    }
  ]
}

Response (201 Created):

{
  "id": "0190f4c2-3d7e-7e55-ac2f-2a3b4c5d6e7f",
  "name": "invoice-triage-agent",
  "tenantId": "0190d1a0-0b1c-7a22-7f0c-8d7e6f5a4b3c",
  "ownerUserId": "0190f3a1-2b6c-7c44-9b1e-1f2a3b4c5d6e",
  "status": "Active",
  "scopeCeiling": {
    "capabilities": ["billing:read", "billing:export"],
    "toolScopes": ["mcp:invoices:list", "mcp:invoices:fetch"]
  },
  "allowedTaskTypes": ["analysis.financial", "summarization.document"],
  "defaultTaskType": "analysis.financial",
  "publicKeys": [
    { "kid": "key-2026-06", "state": "Active", "notAfter": "2027-06-09T00:00:00Z" }
  ],
  "createdAt": "2026-06-09T14:21:07Z",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Business Rules

Data Requirements

AgentIdentity

AgentPublicKey

Security Considerations

• Authentication: API access uses the X-Api-Key header; the Web UI uses cookie auth. Agents themselves never get a secret here — only their public keys are registered for later private_key_jwt authentication (UC-026).
• Authorization / capabilities: agents.read, agents.write, and agents.disable capabilities gate the registry operations; admins compose these into roles via the existing Role/Capability/RoleCapabilityMapping model (capability-based RBAC, no prescribed roles).
• Data protection: Public keys are non-secret but integrity-protected; no private key material is ever accepted or stored. The scope ceiling and governance limits are enforced server-side, never trusted from the client at mint time.
• Audit: Every register/update/disable/revoke/key-rotation event writes an AuditLog row with the actor chain and before/after values; heartbeats and other high-noise events are excluded by design.

Testing Scenarios

Related Use Cases

• UC-026: Agent Credential Issuance — mints ephemeral scoped credentials bounded by this agent's ceiling and governance limits.
• UC-027: On-Behalf-Of Delegation — delegation grants are bounded by the agent's own scope ceiling.
• UC-029: Agent Provisioning UX — the purpose-picker and direct-model-picker paths that set AllowedTaskTypes/DefaultTaskType.
• UC-032: Budget Cap Lattice — supplies the budget-headroom check that gates agent creation.
• UC-033: Agent Plan Budget Lifecycle — consumes PerTurnBudget and the per-agent overlay.
• UC-006: Role-Based Access Control — capability composition for agents.*.
• UC-010: Activity Logging & Audit Trail — the underlying AuditLog surface.
• UC-016: Tenant Provisioning Management — tenant ownership and Top-cap defaults.

Revision History