Agentic Identity Broker - Admin Server API (1.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 a list of all registered agents in the system.

Returns a direct array of agent objects (no envelope). Agents are returned 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

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.

Retrieve detailed information about a specific agent.

Returns the complete agent configuration including all optional fields.

Update configuration for an existing agent.

Update Semantics:

• All fields in the request body will update the agent
• Omitted optional fields are preserved from existing configuration
• 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).

Security: All client_secret fields are redacted as "REDACTED" for confidential services; the property is omitted for public services, which hold no credential

Configure a new third-party OAuth2 service provider.

Validation Rules:

• display_name: Required, max 255 characters
• client_id: Required, unique across all services
• client_secret: Required unless token_endpoint_auth_method is none (encrypted at rest, never returned)
• issuer_uri: Required, must be HTTPS URL
• scopes: Optional. Omit it or provide an empty array when the provider does not use OAuth2 scopes.

Discovery Modes:

1. Automatic Discovery (enable_discovery: true):

   • System fetches endpoints from {issuer_uri}/.well-known/oauth-authorization-server
   • Optional metadata_url can override default discovery location
   • Falls back to manual endpoints if discovery fails

2. Manual Configuration (enable_discovery: false):

   • Requires endpoints.token_endpoint and endpoints.authorize_endpoint

Security: client_secret is encrypted with AES-256-GCM before storage

Retrieve detailed configuration for a specific OAuth2 service.

Security: All client_secret fields are redacted as "REDACTED" for confidential services; the property is omitted for public services, which hold no credential

Update configuration for an existing OAuth2 service.

Update Semantics:

• All fields in the request body will update the service
• Omitted optional fields are preserved from existing configuration
• token_endpoint_auth_method is evaluated from the request alone. Omit it or set it to null to make the service confidential, regardless of its stored value; a client_secret is then required.
• 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

Secret Rotation:

• Provide new client_secret to rotate 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

Security: client_secret is redacted in response

• 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

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

Retrieve metadata about an agent's broker-issued client credentials.

Security: The client_secret is never returned by this endpoint. Only the client_id and timestamps are returned.

Returns 404 Not Found if no credentials have been generated for the agent.

Revoke an agent's broker-issued client credentials.

After revocation, the agent can no longer authenticate using these credentials. Active tokens issued with these credentials remain valid until expiry.

Irreversible: New credentials must be generated via POST after revocation.

Generate a new signing key for the broker's OAuth2 server. The new key is marked as is_current: true but does not start signing tokens until activates_at has passed (grace period = 2 × JWKS Cache-Control: max-age value, currently 600 s). During this window the key is already present in the JWKS response, so every client cache will have learned about it before the first token signed with it appears.

Algorithm Support:

• ES256: ECDSA using P-256 curve and SHA-256 (default, only supported algorithm)

Key Lifecycle:

• New key is immediately published to GET /oauth2/jwks.json
• New key starts signing tokens only after activates_at (now + 600 s)
• Previous current key continues signing during the grace period
• Private key material is never exposed via the API

Retrieve all active signing keys for the broker's OAuth2 server.

Security: Private key material is never included in the response. Only public metadata (kid, algorithm, status, timestamps) is returned.

Keys are returned in creation order (newest first).

Promote an existing signing key to be the current signing key. The current key is used for signing new tokens.

Behavior:

• The specified key becomes is_current: true
• The previous current key is set to is_current: false
• Previous key remains active for token verification

Remove a signing key from the active key set.

Soft Delete: The key is deactivated but retained for audit purposes. Tokens previously signed with this key can no longer be verified.

Constraints:

• Cannot delete the last remaining signing key (returns 409 Conflict)
• Cannot delete the current signing key without first promoting another key