Agentic Identity Broker - Admin Server API (3.0.0)

Returns the current health status of the HTTP server. Each server (end-user and admin) has its own independent health endpoint that reports only that server's status.

This endpoint is public and does not require authentication.

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

Retrieve registered agents. Without external_id, return all agents. With one external_id, return the exact, case-sensitive match, if any. External IDs are unique, so the array contains zero or one agent. Do not trim, normalize, or interpret the value as a pattern. The filter does not match agent IDs, canonical IDs, or client IDs.

Percent-encode reserved characters in the value, such as &, +, and ;. For example, send urn:example:ai-registry:agent:7f3a9c as urn%3Aexample%3Aai-registry%3Aagent%3A7f3a9c. Invalid filters return 400 with error: invalid external_id. This includes empty or repeated values, invalid UTF-8, NUL, more than 255 Unicode code points, malformed percent-encoding, and an unencoded ;. Unknown parameters and malformed query parts outside external_id retain their existing handling.

Returns a direct array of agent objects (no envelope), in no guaranteed order.

Register a new AI agent in the identity broker system.

The client_id field is the upstream OAuth2 client ID used when proxying authorization requests to the upstream server.

client_id uniqueness depends on configuration:

• When multi_agent_client.enabled = false (default): client_id must be unique across all agents. Returns 409 Conflict if a duplicate client_id is detected.
• When multi_agent_client.enabled = true: Multiple agents may share the same client_id. No uniqueness validation is performed.

Validation Rules:

• client_id: Optional; when provided must be non-empty; unique across all agents when multi_agent_client.enabled = false
• display_name: Required, max 255 characters
• description: Required, max 1000 characters
• URLs: Must be valid HTTP/HTTPS URLs if provided; redirect_uris entries follow the redirect_uris schema rules

external_id uniqueness: When supplied, external_id must be valid UTF-8 text with 1–255 Unicode code points and no NUL character, and must not be held by another agent. An empty string returns 400 validation failed. A held value returns 409 conflict with message external_id is already held by another agent. Omit external_id or send null for agents without one; any number of agents may omit it.

ID Generation: System generates a UUID for the agent ID. client_id is not auto-generated — omit it for agents that do not need one.

Idempotently reconcile the agent identified by an external governance ID.

• No agent holds external_id: create one and return 201 Created with Location.
• An agent holds it: update that agent and return 200 OK. The selector never matches agent IDs, canonical IDs, or client IDs.
• Replaying an identical request with no intervening change returns 200 with the unchanged representation, including updated_at. Nothing is written.
• Concurrent first requests with one external ID create exactly one agent. Without If-Match, concurrent different definitions are last-writer-wins; each successful request applies its complete definition.

Selector: exactly one external_id query parameter, 1–255 Unicode code points, valid UTF-8, no NUL, valid percent-encoding, and no unencoded ;. Percent-encode &, +, and ;. Otherwise 400 invalid external_id.

Body: AgentCreateRequest. Omitted external_id takes the selector. A supplied external_id must equal the decoded selector; a different value, "", or null returns 400 invalid external_id.

Update-branch field policy (FR-012):

On creation, omitted optional fields are absent or empty and no client_id is generated. Grants and other relationships of an updated agent are not changed. To clear an existing client_id, use PUT /api/agents/{agent-id} with client_id: null.

Invalid definitions, attributes, and references on either branch return 400 with the existing validation failed envelope. Canonical-ID conflicts, configuration-dependent client_id conflicts (multi_agent_client.enabled), and client-URI identity conflicts return 409 conflict on both branches. Failed requests change no agent. Agent ordering and timestamps follow "Stable Agent Response Presentation" above on create, update, and replay.

Retrieve detailed information about a specific agent.

Returns the complete agent configuration including all optional fields.

Update configuration for an existing agent.

When supplied, external_id must be non-empty and must not be held by another agent (400 validation failed / 409 conflict). Retaining its own external ID is not a conflict. Canonical-ID, client-ID, and client-URI conflicts also return 409.

Update Semantics:

• PUT is a full replacement, not PATCH. Send every field you want to keep
• Omitted or null external_id, governance_url, user_documentation_url, agent_interface_url, service_requirements, redirect_uris, allowed_scopes, and client_uris are cleared
• canonical_id and client_id are the exceptions: omitted preserves the existing value, and explicit null clears it
• created_at timestamp is preserved
• updated_at timestamp is set to current time

client_id uniqueness depends on configuration:

• When multi_agent_client.enabled = false (default): client_id must be unique across all agents (excluding the current agent). Returns 409 Conflict if a duplicate client_id is detected on another agent.
• When multi_agent_client.enabled = true: Multiple agents may share the same client_id. No uniqueness validation is performed.

Validation:

• client_id: Three-state — omitted preserves existing value, explicit null clears it, string value updates it (must be non-empty); unique across all agents (excluding the current agent) when multi_agent_client.enabled = false
• Other fields follow the same rules as creation

Remove an agent from the system.

Cascade Behavior:

• All user grants associated with this agent are automatically deleted
• Deletion is logged for audit purposes

Irreversible: This operation cannot be undone

Retrieve a list of all configured third-party OAuth2 services.

Returns a direct array of service objects (no envelope).

Every object reports credential_source and client_registration. Static confidential services return their client ID and "REDACTED" secret. Static public, CIMD, and DCR services omit the secret. Filesystem services omit inline credentials. Listing never reads files or returns paths or file values.

Configure a new third-party OAuth2 service provider.

Validation Rules:

• display_name: Required, max 255 characters
• credential_source: stored or filesystem; omission selects stored; explicit null and unknown values are invalid
• client_registration: Optional static or cimd. Omission selects cimd for private_key_jwt and static otherwise. Explicit null, empty, or unknown values return 400
• Stored manual client_id: Required and unique under existing validation, except Google derives it and CIMD generates it; discovery selects the client identity
• Stored client_secret: Required for static confidential services. Static public and both CIMD modes accept omitted, null, or empty secret input
• Filesystem: Requires a valid canonical ID, shared-secret authentication, and standard/GitHub flavor
• Filesystem: Rejects either inline field whenever present, including null or empty input
• Manual issuer_uri: Required and HTTPS, subject to existing Google service-account rules; optional for protected-resource discovery with one issuer
• scopes: Optional. Omit it or provide an empty array when the provider does not use OAuth2 scopes.

Filesystem registration never reads files or requires an available binding. Paths belong only to operator configuration and cannot be supplied through this API. Every successful response reports the selected source. Filesystem responses omit both inline fields.

CIMD modes: client_registration: cimd with private_key_jwt is confidential. With none, it is public and needs no CIMD client-authentication key. Both require omitted or null client_id and omitted, null, or empty client_secret. The broker rejects a non-empty caller value, Google flavor, or filesystem source with 400 before provider traffic. It assigns the HTTPS client identifier URL after it creates the service ID. static with private_key_jwt, or cimd with absent or null authentication, returns 400.

Direct metadata discovery: Without resource_url, metadata_url can select an authorization-server document. The existing manual-endpoint fallback remains unchanged.

Protected-resource discovery: Set discovery.resource_url with enable_discovery: true. Omit client_registration, manual endpoints, client credentials, metadata_url, and token_endpoint_auth_method. A supplied registration returns 400 before discovery traffic. An issuer selection is optional for one issuer. The broker derives authorization_params.resource unless the request supplies an explicit value. A selected DCR client needs a non-blank broker client name from deployment configuration, not the service display name. Failures do not create a service.

Security: Static and DCR confidential secrets are encrypted before storage. A DCR secret never appears in an Admin API response.

Retrieve detailed configuration for a specific OAuth2 service.

Every response reports credential_source and client_registration without reading files. Stored responses always include client_id. Static confidential secrets return only "REDACTED"; static public, CIMD, and DCR responses omit the secret. Filesystem responses omit both inline credential fields, file paths, and file values.

Update configuration for an existing OAuth2 service.

Update Semantics:

• PUT remains a full replacement, not PATCH. Existing documented omission exceptions remain unchanged
• credential_source omission preserves the current source. Explicit null and unknown selectors are invalid
• Omitted client_registration resolves to cimd for private_key_jwt and static otherwise, not to the old value. Explicit null, empty, or unknown values return 400
• CIMD public must repeat client_registration: cimd. Without it, PUT resolves to static and fails without an operator client_id
• For manual replacements, token_endpoint_auth_method is evaluated from the complete request. Omitted or null means shared-secret authentication: stored requires an explicit non-empty secret, while filesystem forbids inline credentials. Protected-resource refresh retains the broker-selected method and credentials
• token_endpoint_auth_method: private_key_jwt requires client_id to be omitted or null and client_secret to be omitted, null, or empty. A valid replacement removes any prior static secret and assigns the stable broker-generated HTTPS Client ID Metadata Document URL.
• CIMD confidential to CIMD public or back keeps the client identifier URL. Switching to CIMD confidential requires a usable CIMD client-authentication key
• Switching static to cimd replaces the operator client ID and removes a stored secret only after validation. Switching back requires an operator client_id. Static confidential also requires a new secret
• A switch to static makes the hosted document return 404. Providers can cache the previous document for up to 300 seconds. The broker never falls back to another token authentication method
• Updating a service to token_endpoint_auth_method: none removes the stored credential.
• created_at timestamp is preserved
• updated_at timestamp is set to current time

Source Transitions:

• Stored to filesystem requires explicit filesystem, a valid resulting canonical ID, and neither inline field
• The source change, removal of both stored credentials, and irreversible internal transition evidence commit atomically
• Filesystem to stored requires explicit stored and explicitly supplied non-empty client_id and client_secret
• Returning to stored encrypts the supplied secret before the atomic update. Files never supply reverse-transition credentials
• No-op source selections preserve transition evidence. A source round trip never resets it or rewrites established identities
• Omitted canonical ID preserves the existing ID. Null cannot clear a filesystem canonical ID
• Filesystem rejects static public, both CIMD methods, and Google-flavor replacements and either inline field, including null or empty input
• Validation failures and version conflicts leave the previous source, credentials, and transition evidence unchanged
• Updates never read files or require available bindings. File paths and transition evidence are not administrative inputs

Secret Rotation:

• Provide a new client_secret to rotate stored static confidential-service credentials
• New secret is encrypted before storage
• Old secret is securely discarded

Discovery Re-run:

• If enable_discovery: true, endpoints are re-fetched
• Useful for services that change endpoint URLs

Protected-resource refresh: An omitted issuer_uri retains the active issuer only if fresh resource metadata still advertises it. A different issuer requires explicit selection and zero user sessions. An effective authorization_params.resource change also requires zero user sessions, even when the issuer stays the same. Keep the client method and the exact token authentication method. Preserve the client ID and secret for an unchanged issuer. For a discovery-backed refresh, omitted authorization_params keeps the map and its explicit or derived source. A replacement without resource restores the derived resource. On replacement with manual configuration, omission keeps the parameter map but clears the discovery source and resource source marker. For a manual replacement, an explicit empty map clears all parameters. A discovery-backed rejection writes a safe failure-only status without changing the active service ETag. A manual conversion rejected for an audience change writes no discovery status. A request with discovery.resource_url must omit client_registration. Presence returns 400 before discovery traffic. Hosted CIMD reports cimd. DCR reports static. The selected discovery.client_method remains authoritative.

Security: Static confidential-service client_secret values are redacted in responses. Static public, CIMD, and DCR responses omit the property. Filesystem responses omit inline credentials, paths, and file values. Every response reports credential_source and client_registration.

• protected_resources omitted or null: preserves the current protected-resource set
• protected_resources present (including []): replaces the entire set and requires If-Match

Remove an OAuth2 service from the system.

Referential Integrity Check:

• Operation fails with 409 Conflict if user grants reference this service
• Administrators must revoke or modify grants before deletion
• This prevents breaking active user permissions

Irreversible: This operation cannot be undone

Read stored status without contacting a resource or authorization server. A missing operator principal returns 401 before the service is read. A failed refresh keeps the last successful issuer, client method, and resource URL. Manual services return not_applicable and null discovery fields.

Adds the body resource_uri after server-side validation and normalization. A newly added URI returns 201. A URI already owned by this service returns 200 with the set unchanged; a URI owned by another service returns 409 Conflict.

Idempotently adds the resource URI identified by the fully percent-encoded final path segment. The server decodes the segment exactly once, then validates and normalizes it. Adding a URI this service already owns returns 200 with the set unchanged; a URI owned by another service returns 409.

Atomically changes the percent-encoded source URI in {resource} to the target URI in the body. A source equal to the normalized target succeeds as a no-op. A target already owned by any service returns 409; a source not owned by this service returns 404.

Removes the resource identified by the fully percent-encoded path segment after decoding exactly once and normalizing it. A resource not owned by this service returns 404.

Creates a new named permission set grouping OAuth2 scopes across one or more third-party services.

Validation rules:

• name must be unique (409 Conflict if duplicate)
• service_scopes must contain at least one entry (400)
• Each service_id in service_scopes must reference an existing service (400)
• Each scopes list may be empty for a scope-less service; supplied values must be non-empty (400)

Returns all permission sets. Optionally filter by service ID to find all permission sets that include scopes for a specific third-party service.

Fully replaces a permission set's name, description, and service_scopes. All fields are required (PUT semantics — full replacement).

Note: Changing service_scopes takes effect immediately; the next token exchange for any grant referencing this set will use the updated scopes (cache TTL ≤ 60s delay).

Deletes a permission set by ID.

Rejected with 409 Conflict if any agent's permission_sets list references this ID, or if any active user grant references this permission set. Admins must remove the permission set from all agents and revoke all active grants referencing it before deletion.

Irreversible: This operation cannot be undone.

Generate new broker-issued client credentials for an agent, or rotate existing credentials. This allows the broker to act as an OAuth2 authorization server and authenticate agents directly.

Runtime usage: Agents use the client_id returned here as client_id at the /oauth2/token endpoint. The value is the agent's UUID.

First Generation (no existing credentials):

• Returns 201 Created with new client_id (metadata) and client_secret
• The client_secret is only returned in this response — store it securely

Rotation (existing credentials):

• Returns 200 OK with new credentials and previous_invalidated_at timestamp
• Previous credentials are immediately invalidated
• Active tokens issued with previous credentials remain valid until expiry