OAuth Clients

Register OAuth client

Changed on

Register a new OAuth client for third-party application integration.

The generated client_id and client_secret are returned in the response. The secret is shown only once — store it securely.

post/admin/oauth-clients

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /admin/oauth-clients
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Request body

allowed_scopesstring[] nullable

If set, restricts which scopes this client may request. An empty list denies all non-OIDC scopes. Null means unrestricted (all scopes permitted).

consent_model'user' | 'agent'

What a user's consent grants for this client. user keeps today's act-as-user semantics; agent marks the client for agent-bound consent (the MCP path).

descriptionstring nullable

Optional description of the client.

namestring required

Human-readable name for the client.

redirect_urisstring[] required

Allowed OAuth callback URLs. At least one required.

require_consentboolean

Whether to show a consent screen during authorization. Set to false for trusted first-party integrations.

token_endpoint_auth_method'client_secret_basic' | 'none'

Client authentication method at the token endpoint. client_secret_basic creates a confidential client with a generated secret; none creates a public (secret-less) client that relies on PKCE alone — no secret is generated or returned.

Example request

{
  "description": "My application production deployment",
  "name": "my-app-production",
  "redirect_uris": [
    "https://app.example.com/auth/callback"
  ],
  "require_consent": true
}

Response

Successful Response

activeboolean required

Whether the client is enabled; false for disabled, pending or denied clients.

active_grant_countinteger

Number of active consent→agent grants for this client. Computed on the read endpoints (list/get); write-path responses report 0.

allowed_scopesstring[] nullable required

Scopes this client may request. Null means unrestricted.

approval_statusstring required

Admin approval lifecycle: pending, approved, or denied. Only approved clients may enter OAuth flows; active remains the independent kill switch.

client_idstring required

Public client identifier used in OAuth flows.

client_secretstring nullable required

The client secret. Shown only once at creation — store it securely. Null for public (secret-less) clients.

consent_modelstring required

What a user's consent grants for this client: user or agent.

created_atstring date-time required

When the client was created (RFC 3339).

created_bystring nullable required

ID of the actor that created the client; null if not recorded.

descriptionstring nullable required

Description of the client; null if none.

idstring required

Record ID of the OAuth client (oac_…), not its public client_id.

namestring required

Human-readable name for the client.

redirect_urisstring[] required

Allowed OAuth callback URLs.

registration_sourcestring required

How the client entered the registry: admin or dcr.

require_consentboolean required

Whether a consent screen is shown during authorization.

software_idstring nullable required

RFC 7591 software identifier claimed at registration, if any.

token_endpoint_auth_methodstring required

Client authentication method at the token endpoint: client_secret_basic (confidential) or none (public, PKCE-only).

updated_atstring date-time nullable required

When the client was last updated (RFC 3339); null if never updated.

Example response

{
  "active": true,
  "active_grant_count": 0,
  "allowed_scopes": [
    "agents:read",
    "credentials:read"
  ],
  "approval_status": "approved",
  "client_id": "oc_abc123...",
  "client_secret": "<redacted>",
  "consent_model": "user",
  "created_at": "2026-08-18T12:00:00Z",
  "created_by": "usr_abc123",
  "description": "My application production deployment",
  "id": "oac_2NxYz...",
  "name": "my-app-production",
  "redirect_uris": [
    "https://app.example.com/auth/callback"
  ],
  "registration_source": "admin",
  "require_consent": true,
  "software_id": "com.example.my-app",
  "token_endpoint_auth_method": "client_secret_basic",
  "updated_at": "2026-08-18T12:00:00Z"
}

Changes