Agentic Identity Broker - End-User API (1.2.0)

Returns the current health status of the end-user HTTP server.

This endpoint does not require authentication and is intended for:

• Load balancer health checks
• Kubernetes liveness/readiness probes
• Monitoring systems
• Service discovery health validation

Status Codes:

• 200 OK: Server is healthy and accepting requests
• 503 Service Unavailable: Server is starting, shutting down, or unhealthy

Health States:

• healthy: Server is operational and processing requests normally
• starting: Server is initializing (binding to port, setting up routes)
• shutting_down: Graceful shutdown in progress, completing in-flight requests
• unhealthy: Server encountered an error and requires restart

The response may also include component-level health in components. Components report healthy or degraded and never change the HTTP status or the top-level status.

• upstream_jwks (proxy and hybrid modes): freshness of the upstream key set that the broker republishes.
• trust_anchor_key_files (any mode, when a trust anchor uses jwks_file): degraded when the latest re-read of any key-set file failed. The broker keeps verifying with the last valid key set until that trust anchor's maximum refresh interval expires.

Returns information about the currently authenticated user.

The user information includes:

• Principal: Unique identifier (email, UUID, etc.) from authentication system
• Display Name: Human-readable name for display in UI
• Picture URL: Optional avatar/profile picture URL

The principal is extracted from the X-Remote-User header set by the upstream authentication proxy (oauth2-proxy, nginx, etc.).

Use Cases:

• Display user info in application header
• Show "logged in as" indicators
• Personalize UI with user's name/avatar
• Verify authentication status

Returns a list of all agents to which the current user has granted access.

Each agent delegation includes:

• Agent ID: Unique identifier for the agent
• Display Name: Human-readable agent name
• Logo URL: Optional agent logo/icon
• Active Grant Count: Number of third-party services delegated
• Last Modified: When the delegation was last updated
• Expires At: Optional expiration date (null = indefinite)

Response Characteristics:

• Returns empty array if user has no active delegations
• Only includes agents with at least one active grant
• Ordered by display name in ascending order. Agents with the same display name are ordered by agent ID in ascending order.

Use Cases:

• Dashboard showing all active agent delegations
• Quick overview of user's consent status
• Navigation to detailed agent management

Returns detailed information about a specific agent and all available third-party OAuth2 services that can be delegated to that agent.

Agent Detail Includes:

• Agent metadata (name, description, logo)
• Governance documentation URL
• User documentation URL
• Agent interface URL

Service Information Includes:

• Service ID (UUID)
• Service name (e.g., "Google Drive", "GitHub")
• Service logo URL
• The OAuth2 permissions the agent can receive for the service, with human-readable descriptions. For a require_all_scopes requirement, this is the sorted, deduplicated union from this agent's assigned Permission Sets that cover that service.

Use Cases:

• Display agent information before granting access
• Show available services and permissions
• Help users make informed consent decisions
• Link to governance and documentation

Returns all active grants the authenticated user has granted to the specified agent.

Grant Information Includes:

• Grant ID (UUID)
• Principal (user identifier)
• Agent ID
• Valid until date (null = indefinite)
• Delegated OAuth2 tokens (services and scopes)
• Creation timestamp
• Last update timestamp

Response Characteristics:

• Returns empty array if no grants exist
• Only includes active (non-expired) grants
• Typically one grant per user-agent pair (upsert semantics)

Use Cases:

• Check if user has existing grants before showing consent UI
• Pre-populate consent form with current grants
• Display current delegation status

Creates a new grant or updates an existing grant for the specified agent.

Upsert Semantics:

• One grant per user-agent pair

• Subsequent POSTs update the existing grant

• Previous granted permission sets are replaced (not merged)

Grant Expiration:

• valid_until is optional (omit for indefinite grant)
• Must be a future date if specified
• Expired grants are automatically filtered out

Revocation (Special Case):

• Submit empty granted_permission_sets object to revoke

• Returns 204 No Content on successful revocation

• Deletes the grant entirely

Session-Based Consent (FR-029):

• Use session_token query parameter to resume an OAuth2 authorization flow after consent
• Applies to all agent modes: local, proxy, and CIMD
• Token is a self-contained JWE carrying all authorization session claims (agent_id, principal, original_url, TTL) — no server-side session lookup is performed
• Returns HTTP 201 with redirect_url field containing the original authorization URL (with original state, redirect_uri, PKCE, and client_id parameters intact)
• Frontend must navigate to redirect_url using window.location.href to resume the OAuth2 flow
• Returns 400 Bad Request with error code session_expired if the token is invalid or expired
• Returns 400 Bad Request if the session agent does not match the agent in the URL path
• Returns 403 Forbidden if the session principal does not match the authenticated user

Standalone Consent Management:

• Requests without session_token are treated as direct consent-management operations (not authorization resumption)
• Returns HTTP 201 with grant data only (no redirect_url field)

Validation:

• All service IDs must exist and be available to the agent
• All scopes must be valid for the specified services
• At least one scope required per service
• Returns 400 Bad Request with details if validation fails

Use Cases:

• User grants initial access to an agent
• User updates existing grant (adds/removes services or scopes)
• User revokes all access to an agent
• Redirect to authorization flow continuation URL after consent approval

Permanently deletes the authenticated user's grant for the specified agent. After revocation, the agent can no longer perform token exchanges on behalf of the user.

Important: This action only removes the delegation grant. Connected OAuth2 sessions (e.g., GitHub, Google) remain active and are NOT terminated by this action. Users may manage OAuth2 sessions separately.

Idempotency: Non-idempotent — returns 404 if no grant exists. To silently revoke if a grant exists, use POST /api/consent/agents/{agent-id}/grants with an empty granted_permission_sets object.

Security: Only the grant owner may revoke. The principal is derived from the X-Remote-User authentication header. Cross-user revocation is not possible — grants are scoped to the authenticated principal.

Initiates an OAuth2 authorization code flow. The broker validates the agent, checks consent, and either redirects to the upstream OAuth2 authorization server or issues an authorization code directly (local/hybrid mode).

client_id semantics: In proxy mode the client_id MUST be the agent's internal UUID (agent.id). In local/hybrid mode the client_id may also be an HTTPS URL identifying a Client ID Metadata Document (CIMD) when CIMD is enabled.

redirect_uri validation (all modes):

• redirect_uri is matched against the agent's redirect_uris. For a CIMD client_id, it is matched against the fetched document's redirect_uris.
• Loopback http URIs match on any port.
• A private-use scheme URI such as github-app://oauth/callback matches only character for character. For a CIMD client, the agent's redirect_uris must also list it.
• The broker never redirects to an unregistered redirect_uri.

Local/Hybrid Mode: When the broker acts as its own OAuth2 authorization server:

• If user has an active grant, redirects to redirect_uri with code and state
• If no active grant exists, redirects to the consent UI for user approval
• Supports PKCE (RFC 7636) with code_challenge and code_challenge_method

Proxy Mode: When proxying to an upstream OAuth2 server:

• Redirects to the upstream authorization endpoint with PKCE parameters
• Agent ID is embedded in the state token for callback correlation

Error Handling (RFC 6749 §4.1.2.1):

Direct JSON responses (no redirect — RFC 6749 §4.1.2.1):

• invalid_client (400): client_id is not a valid UUID OR no agent with that UUID exists; a retrieved CIMD document is malformed or violates policy, including an unallowlisted private-use redirect URI
• invalid_redirect_uri (400): redirect_uri not registered on the agent
• invalid_request (400): Missing PKCE parameters, or redirect_uri not registered for a CIMD client
• unsupported_response_type (400): response_type is not code
• server_error (500): Internal infrastructure failure, or a CIMD metadata document cannot be retrieved because of a timeout, connection failure, or upstream server error

Redirect responses (error appended to redirect_uri as query params; redirect_uri has been validated):

• invalid_scope: Requested scope exceeds the agent's allowed_scopes
• access_denied: User explicitly denied consent
• server_error: Proxy mode — agent has no upstream client_id configured

Exchange a token for another token, or obtain a token directly. This endpoint supports three grant types:

Client Credentials Grant (RFC 6749 §4.4 - Issue Token Mode)

Authenticate the agent directly using broker-issued client credentials and obtain an access token. Used when the broker acts as an OAuth2 authorization server.

• grant_type: client_credentials
• client_id: Agent UUID (agent.id)
• client_secret: Broker-issued client secret
• scope: (optional) Space-delimited requested scopes

Authorization Code Grant (RFC 6749 - Issue Token Mode)

Exchange an authorization code for an access token. Supports PKCE for public clients.

• grant_type: authorization_code
• client_id: Agent UUID (agent.id)
• client_secret: Broker-issued client secret
• code: Authorization code from /oauth2/authorize
• redirect_uri: Must match the URI used in the authorization request
• code_verifier: (optional) PKCE code verifier (RFC 7636)

CIMD Client Authentication (private_key_jwt)

In local or hybrid mode with CIMD enabled, a pre-registered CIMD client may declare token_endpoint_auth_method: private_key_jwt. For authorization_code and refresh_token requests, it must send client_assertion_type and a signed client_assertion. The assertion must use a key published by the client, identify the client in iss and sub, target the broker issuer or canonical token endpoint, and include an unexpired, single-use jti. Authorization-code exchange still requires the registered redirect_uri and PKCE S256 verifier. A client secret or Authorization header must not accompany the assertion. Assertion failures return invalid_client; malformed assertion parameters return invalid_request; key-set or metadata fetch failures return server_error. Failed authentication does not consume the code or rotate a refresh token.

Authorization Code Grant (RFC 6749 - Proxy Mode)

Exchange an authorization code for an access token via the upstream OAuth2 server. This is the standard OAuth2 authorization code flow used for initial user consent. The broker forwards form fields, including client_secret when supplied, in the request body and forwards only the validated form Content-Type request header. It does not forward credential headers such as Authorization, cookies, or proxy identity headers. The broker returns only Content-Type, Cache-Control, Pragma, and WWW-Authenticate from upstream responses. It never returns upstream cookies or arbitrary response headers.

Token Exchange Grant (RFC 8693)

Exchange a token issued by the Upstream OAuth2 Server for a third-party OAuth2 token stored in the token vault.

Third-party exchange requires the exact subject_token_type urn:ietf:params:oauth:token-type:access_token and client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Missing, empty, or different identifiers return 400 invalid_request; the broker does not supply defaults.

All token grants require exactly one Content-Type field. Per RFC 6749 Section 3.2, a parameter sent without a value is treated as omitted. A singleton form parameter with more than one non-empty value returns 400 invalid_request. These parameters are grant_type, client_id, client_secret, code, redirect_uri, refresh_token, code_verifier, scope, subject_token, subject_token_type, client_assertion, client_assertion_type, actor_token, actor_token_type, and requested_token_type.

The resource and audience parameters are repeatable under RFC 8693 Section 2.1. Repeated resource values that normalize to the same URI are accepted. Distinct resource values return 400 invalid_target because the broker returns one service token.

The token exchange flow:

1. Gateway authenticates using client_assertion JWT (gateway identity)
2. System validates subject_token JWT (contains principal + agent identifier)
3. System evaluates CEL authorization policy
4. System looks up service by resource URI in protected_resources
5. System verifies user grant exists for agent+service
6. System retrieves (and optionally refreshes) stored third-party tokens
7. System returns RFC 8693 compliant response

Authentication for Token Exchange:

• client_assertion: Gateway JWT authenticated against upstream OAuth2 JWKS
• subject_token: User JWT containing principal and agent identifier
• Both validated to have correct issuer, audience, and expiration

Resource Discovery:

• resource parameter must match a protected_resource on ThirdpartyOAuth2Service
• URIs are normalized (trailing slashes removed) before matching
• Missing match returns 400 invalid_target error
• Ambiguous registered resource configuration returns 500 server_error.

User Grant Verification:

• User must have active (non-revoked, non-expired) grant to agent+service
• A missing, expired, or unusable grant returns 403 access_denied with error_uri set to the agent consent-management page (<public URL>/agents/{agent-id}). This includes empty grants, uncovered services, and undeclared or removed permission sets. The broker denies before any token-vault lookup.

Session Recovery:

• A missing session, a session whose refresh token the provider has rejected, or an expired session without a stored refresh token, returns 400 invalid_grant. Its error_uri starts authorization for the resolved service at <public URL>/api/third-party/{service-id}/oauth2/authorize with an encoded <public URL>/sessions return URI.
• When the provider rejects the stored refresh token with HTTP 4xx (except 429) and OAuth error invalid_grant, the broker returns 400 invalid_grant with the same service-specific error_uri. The stored tokens are left unchanged, and the rejection is recorded. Later exchanges return the same error without contacting the provider, even while the stored access token has not expired, until the user reconnects the service.
• A missing required client-identity association or a mismatch with the selected client ID returns 400 invalid_grant with the same service-specific error_uri. The broker stops before provider authentication and leaves the established session unchanged.
• Any other refresh failure (for example provider invalid_client, a provider 5xx, an unparseable provider response, or a transport, storage, or decryption failure) returns 500 server_error without error_uri. Provider error descriptions are never returned.
• Invalid subject credentials return 400 invalid_grant; invalid client assertions return 401 invalid_client. Neither is a provider-session recovery request.
• Descriptions are credential-free protocol summaries, not stable diagnostic identifiers. Clients use error and the optional error_uri to choose the recovery flow.

Token Exchange Grant (RFC 8693) — User Impersonation (local mode only)

Mints a locally issued access token representing a subject user and attributing the acting party with the standard act claim. Available only in local mode; proxy and hybrid reject it.

The routing-only oauth2_authorization_server.impersonation.audience_prefix activates impersonation only when exactly one request audience is <audience_prefix>/<canonical lower-case AgentID UUID or canonical_id>. Both forms resolve the same registered target agent, which supplies minted UUID agent_id and local-token CEL agent.*. A signed client assertion is the privileged-client identity for authorization and audit only. The routing audience is never copied into issued aud; the existing local token_claims_expression emits aud or leaves it absent exactly as normal local issuance does. Activation precedes the third-party mandatory-resource check.

• grant_type: urn:ietf:params:oauth:grant-type:token-exchange
• audience: one <audience_prefix>/<canonical lower-case AgentID UUID or canonical_id> URI
• client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• client_assertion: signed JWT authenticating the privileged client
• actor_token_type: urn:ietf:params:oauth:token-type:jwt
• actor_token: signed JWT identifying the actor
• subject_token_type: urn:ietf:params:oauth:token-type:jwt; a matching rule's verification: none selects the unsigned-subject profile
• subject_token: signed subject JWT, or, for a matching verification: none rule, an unsigned alg:none JWT
• requested_token_type: optional; when present MUST equal the access-token type

resource is rejected with invalid_request. An optional scope requests values from the resolved target agent's allowed_scopes; an empty target allow-list is unrestricted, and offline and offline_access are always permitted refresh-token scopes. An out-of-list non-reserved value returns invalid_scope. The normal local JWT and response carry non-empty granted scope. Signed credentials are validated for signature, issuer, audience, expiry, and not-before before a CEL authorization predicate decides the request. Bare suffixes and suffixes matching neither identifier form return invalid_request; a well-formed UUID or canonical-ID suffix whose target is unknown returns invalid_target. No-match precedence is access_denied > invalid_request > invalid_client.

After a rule authorizes a human-category request, the broker requires an active user delegation for the extracted subject and target agent. A missing or expired delegation returns 403 access_denied with the existing RFC 6749 error_uri response member set to the authenticated user's target-agent consent page. The response intentionally does not distinguish a missing delegation from an expired one. An unverified subject has no exemption; a delegation lookup failure returns 500 server_error without error_uri.

Agent subjects

Each impersonation rule lists accepted allowed_subject_categories: human, agent, or both. Omission means [human]. No request parameter selects the category. A request is agent-category only when the rule's subject role is signed, its credential verifies, and its raw string sub is byte-for-byte equal to the canonical UUID of the target selected by audience. Every other request is human-category, including every unsigned (verification: none) subject. Aliases, display names, other agents' UUIDs and different UUID spelling do not qualify. All configured principal extractions must still succeed; an eligible agent's represented subject is the target UUID, not necessarily the extracted principal.

A category-ineligible rule falls through. No match returns the existing generic 403 access_denied (impersonation not permitted) without error_uri. Signed exact equality on human-only or omitted-category rules is ineligible even with active same-text human delegation. Eligible, CEL-authorized agents need no delegation, never return a consent-required error_uri, and create no grant or session. Human delegation denials remain terminal and are never retried as agents.

Agent tokens have reserved sub and agent_id equal to the target UUID and existing act (iss: verified actor issuer, sub: extracted actor). No category claim is added. token_claims_expression cannot override those reserved identities. Subject email extraction is not evaluated and no credential-derived email is supplied; output email remains policy-owned. Issuer, signing, lifetime, scope and audience policy are unchanged.

Third-party exchange of agent-subject tokens

After validating credentials and extracting the principal, before agent-ID extraction, authorization, resources, grants or sessions, third-party exchange evaluates token_exchange.claim_extraction.agent_subject_expression. Its guarded default is has(subject_token.sub) && has(subject_token.agent_id) && subject_token.sub == subject_token.agent_id. A match returns 403 access_denied with description agent-subject tokens cannot be exchanged for third-party service tokens, no error_uri, and no human grant, session or provider access, including same-text human state. Default detection also rejects equal-claim legacy, mapped/unsigned human and trusted external issuer tokens. An evaluation error, timeout or dynamic non-boolean output returns 500 server_error without consent recovery or human-state access, never false.

A configured expression replaces the default entirely, with no additional built-in check. It must reference subject_token.sub; otherwise the broker refuses to start, so false cannot be configured. Operators must retain broker agent-token matching, for example by preserving the default as a disjunct. A non-matching result continues existing checks, which may read matching human grants/sessions and return consent errors. Such overrides remove categorical rejection and same-text human-credential isolation.

Returns the broker's aggregated public signing keys in JWK Set format (RFC 7517). It does not publish CIMD client-authentication keys.

Clients use this single endpoint to verify any token the broker asks them to trust, regardless of operating mode. Only public key material is included — private keys are never exposed.

Mode-dependent content:

• local mode: returns only the broker's locally-generated signing keys.
• proxy mode: republishes the upstream authorization server's public keys verbatim.
• hybrid mode: returns the union of local signing keys and upstream keys in a single JWKS document. If any kid appears in both sets, the endpoint returns 500.

Availability: Served in all three modes (local, proxy, hybrid). Returns 503 if the upstream JWKS is unavailable (proxy/hybrid modes). Returns 500 if a duplicate kid is detected across local and upstream key sets (hybrid mode).

Caching: Successful responses include Cache-Control: public, max-age=300. After a signing-key removal commits, a direct request beginning on any broker replica omits the key or returns an error if the key-set revision cannot be checked. Requests already in flight may still return an earlier snapshot. Previously fetched responses can remain in verifier or intermediary caches; the broker cannot enforce a third-party verification deadline.

Key Rotation: Newly stored keys are available on the next direct JWKS request. Previous keys remain in the broker's set until removed by an admin.

Returns the public Client ID Metadata Document for a CIMD confidential or CIMD public service. The returned client_id exactly equals this retrieval URL. The document uses the end-user public URL as its base and contains no private key material or secrets. A CIMD public service returns the document without a CIMD client-authentication key. Its document has no jwks_uri or token_endpoint_auth_signing_alg.

Returns the public ES256 client-authentication keys for a CIMD confidential service. A CIMD public service returns the uniform JSON 404, even without a CIMD client-authentication key. Keys come only from the cimd_client_authentication domain. The set can include a generated key during its activation grace period and retains non-current keys until an operator removes them. It never includes token-signing keys, upstream keys, private JWK members, encrypted key material, or secrets.

Returns the broker's OAuth2 authorization server metadata as defined in RFC 8414. This enables dynamic client discovery of the broker's OAuth2 capabilities and endpoints.

Mode-specific behavior:

• proxy mode: issuer is the broker's own public URL. jwks_uri points to the broker's /oauth2/jwks.json endpoint, which republishes upstream keys.
• local mode: issuer is the broker's own public URL. jwks_uri points to the broker's /oauth2/jwks.json endpoint, which serves locally-generated signing keys.
• hybrid mode: issuer is the broker's public URL. jwks_uri points to the broker's /oauth2/jwks.json endpoint (union of local and upstream keys). The metadata reflects the union of capabilities for both proxy and local grant types.

Caching: Responses include Cache-Control: public, max-age=3600 to allow clients to cache metadata for 1 hour.

No Authentication: This endpoint is publicly accessible as required by RFC 8414.

Returns one summary for each third-party OAuth2 session of the authenticated user. Services without a session are not listed.

Each summary includes:

• Session initiation timestamp
• Reauthentication status and access-token expiry status
• Number of agents depending on this session, derived only from grants owned by the authenticated session principal
• Encryption status indicator

Starts third-party OAuth2 authorization for the specified service with PKCE. It redirects the browser to that service's provider, not the broker's /oauth2/authorize endpoint. A successful provider callback returns to the validated redirect_uri. RFC 8693 recoverable session errors link to this GET with redirect_uri set to the configured public URL's /sessions page. For example: https://broker.example.com/api/third-party/550e8400-e29b-41d4-a716-446655440000/oauth2/authorize?redirect_uri=https%3A%2F%2Fbroker.example.com%2Fsessions.

The broker seals the principal, PKCE verifier, service ID, and return URI in JWE state. The return URI must have the configured public origin.

Initiates an OAuth2 authorization code flow with PKCE when the consent page must preserve selections or return-page query parameters in its current tab.

The same-origin form body supplies the bare UUID consent_state_id. The broker seals it in the private JWE state claim of the provider-facing authorization request. Only a validated success callback includes it in the browser return URL. The redirect_uri field must match the configured public origin and carry only the return path; the browser retains its original return URL in sessionStorage. State tokens of 6,000 bytes or more are rejected before provider redirect.

Processes the OAuth2 callback after user authorization at the third-party.

PKCE applies to every service; the authorization-code exchange presents a client credential only for confidential services.

Validates:

• State token decrypts successfully (JWE)
• State token is not expired
• Principal in token matches current authenticated principal (CSRF protection)
• Service ID in token matches path parameter

On success:

• Exchanges authorization code for access/refresh tokens (with PKCE)
• Encrypts tokens using EncryptionPort
• Stores a new session only if no competing callback already created it
• Reconnects replace credentials only if the session still matches the private callback generation sealed when authorization began. The first completed callback from a shared starting state wins; competing callbacks return success without replacing its credentials. A later deliberate reconnect captures the new generation. Refresh does not invalidate a reconnect, and reconnect cannot recreate a deleted session.
• If an accepted reconnect response omits refresh_token, the broker clears the stored refresh token and its expiry to prevent mixing upstream accounts. The connection requires login again after the new access token expires.
• Redirects to the original redirect_uri with success=true and service_id; for form-initiated flows, also adds the validated consent_state_id so the originating tab can recover its return-page data and remove that ID from the URL

On error:

• Redirects user to sessions page with error message

Returns detailed information about the user's session with a third-party service, including only agents with grants owned by the authenticated session principal that depend on this session. Used to populate the session card and termination warning dialog.

Terminates the user's session with a third-party service by deleting stored tokens. Returns information about affected agents for the confirmation dialog shown before this request.

Note: This does not revoke tokens at the third-party service.

Agents that were using this session will detect the missing session and request re-authentication.

Forces an immediate OAuth2 access-token refresh for the user's session with a third-party service, using the stored refresh token via the RFC 6749 refresh_token grant. Unlike the transparent refresh performed during token exchange, this refreshes even when the current access token has not yet expired. Requires a stored refresh token that the provider has not rejected.

Returns a list of agents that would lose access if the user terminates their session with this third-party service. Used to populate the termination warning dialog.

Creates a pending approval record for a tool invocation that requires human-in-the-loop authorization. Called by ExtProc when a tool call is intercepted that requires approval. Dual-auth required: subject token + client assertion. The subject token binds the request to user/agent context, while the client assertion proves the trusted gateway caller that is allowed to mint approval prompts. Idempotent: returns existing record for duplicate pending requests.

Returns all active approvals grouped by (principal, agent) pair. Supports long-poll via If-None-Match + X-Long-Poll-Timeout headers. Auth: client assertion only (CEL-validated). No subject token is required because this is a gateway control-plane sync channel rather than a user-facing operation.

Returns all pending approvals for the authenticated user. Used by the approval and tool authorization UIs. Auth: acting user principal from the browser auth layer (for example X-Remote-User in pre-auth deployments).

Returns all permanent approvals and denials for the authenticated user. Used by the consent management UI. Auth: acting user principal from the browser auth layer (for example X-Remote-User in pre-auth deployments).

Retrieves a tool approval record by ID for the Approval UI. Auth: acting user principal from the browser auth layer; principal must match.

Transitions a pending approval to approved state with selected persistence scope. Auth: acting user principal from the browser auth layer; principal must match.

Transitions a pending approval to denied state. With persistence: permanent, blocks the exact tool for this principal and agent until revocation, regardless of arguments or session. Clears parameter constraints. ExtProc enforces the denial before matching approvals and does not create another approval request. Auth: acting user principal from the browser auth layer; principal must match.

Marks an approved once-persistence approval as consumed. Auth: subject token only (Bearer); principal must match. Idempotent: consuming already-consumed returns 200. No client assertion is required because this is a per-approval, principal-scoped machine mutation.

Revokes a permanent approval or denial. Auth: acting user principal from the browser auth layer; principal must match.