OAuth App Registrations

Register a shared OAuth application

Changed on

Register a shared OAuth application that users on this instance can SSO through.

The client secret is stored encrypted and never returned by any read endpoint — reads only expose has_client_secret + secret_last_rotated_at. Connect sessions waiting for an OAuth app for the registration's API move on to it right away.

post/oauth-app-registrations

Request

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

Request body

OR

Example request

{
  "api_vendor": "github",
  "authorize_url": "https://github.com/login/oauth/authorize",
  "catalog_api_id": "github.com/api.github.com",
  "client_id": "Iv1.a1b2c3d4",
  "client_secret": "<paste-client-secret-from-vendor-console>",
  "default_scopes": [
    "repo",
    "read:user"
  ],
  "display_name": "GitHub",
  "flow_kind": "authorization_code",
  "name": "MyOrg GitHub",
  "token_url": "https://github.com/login/oauth/access_token"
}

Response

Successful Response

api_vendorstring required

Vendor registry key the registration connects.

authorization_endpointstring nullable

Device authorization endpoint URL; null for authorization-code registrations.

authorize_urlstring nullable

Authorization endpoint URL; null for device-authorization registrations.

catalog_api_idstring required

Catalog API slug this OAuth app targets (e.g. 'googleapis-com/gmail'). Feeds credential.catalog_api_id at connect time so the operations preview resolves against a real registered API.

client_idstring required

OAuth client ID of the app.

created_atstring date-time required

When the registration was created (RFC 3339).

created_bystring nullable required

ID of the actor that created the registration.

default_scopesstring[] nullable

Scopes requested by default; null if none are set.

dependent_credential_countinteger required

Number of credentials minted through this registration.

display_namestring required

Vendor family label ('Gmail'), shown alongside the admin's per-registration 'name' on the picker card.

flow_kind'authorization_code' | 'device_authorization' required

Which OAuth flow a registration supports.

has_client_secretboolean required

Whether a client secret is stored.

idstring required

Unique ID of the OAuth app registration.

is_activeboolean required

Whether the registration is active.

namestring required

Admin-chosen name of the registration.

secret_last_rotated_atstring date-time nullable required

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

token_endpointstring nullable

Token endpoint URL; null for authorization-code registrations.

token_urlstring nullable

Token endpoint URL; null for device-authorization registrations.

updated_atstring date-time required

When the registration was last updated (RFC 3339).

Example response

{
  "api_vendor": "github",
  "authorization_endpoint": "https://github.com/login/device/code",
  "authorize_url": "https://github.com/login/oauth/authorize",
  "catalog_api_id": "github.com/api.github.com",
  "client_id": "Iv1.a1b2c3d4",
  "created_at": "2026-01-15T09:30:00Z",
  "created_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "default_scopes": [
    "repo",
    "read:user"
  ],
  "dependent_credential_count": 4,
  "display_name": "GitHub",
  "flow_kind": "authorization_code",
  "has_client_secret": true,
  "id": "oar_6968b39821e5f89a6975f501",
  "is_active": true,
  "name": "MyOrg GitHub",
  "secret_last_rotated_at": "2026-01-20T14:05:00Z",
  "token_endpoint": "https://github.com/login/oauth/access_token",
  "token_url": "https://github.com/login/oauth/access_token",
  "updated_at": "2026-01-20T14:05:00Z"
}

Changes