Platform OAuth API

Reference for the Platform OAuth endpoint group — 10 endpoints.

Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.

Authentication#

All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.

Endpoints#

GET /api/v1/platform/.well-known/jwks.json#

Platform Jwks

Platform-level JSON Web Key Set endpoint.

Returns the public keys used to verify platform token signatures. These are the same keys used for tenant-level tokens.

Responses:

GET /api/v1/platform/oauth/.well-known/openid-configuration#

Platform Openid Configuration

Platform-level OpenID Configuration.

Returns minimal configuration for platform-level OAuth.

Responses:

GET /api/v1/platform/oauth/authorize#

Platform Authorize

Platform-level OAuth 2.0 Authorization endpoint.

This endpoint is for GLOBAL-scoped applications that need to authenticate users across any tenant. It redirects to a tenant-agnostic login page where the user enters their email, and the system determines the appropriate tenant.

Flow:

1. Application redirects user here with OAuth params
2. We validate the client_id is a GLOBAL app
3. Redirect to auth UI login page (without tenant context)
4. User enters email -> system identifies tenant
5. Continue with tenant-scoped OAuth flow

Parameters:

Responses:

POST /api/v1/platform/oauth/device/authorize#

Device Authorize

Device Authorization Request (RFC 8628 Section 3.1).

The device calls this to get a device_code and user_code.

Parameters:

Request body:

Required.

• application/x-www-form-urlencoded → Body_device_authorize_api_v1_platform_oauth_device_authorize_post

Responses:

GET /api/v1/platform/oauth/device/verify#

Device Verify Info

Get info about a device code for the verification page. Returns the application name and requested scopes.

Parameters:

Responses:

POST /api/v1/platform/oauth/device/verify#

Device Verify Complete

User approves or denies the device authorization request. Requires the user to be authenticated (via SSO cookie or session).

Responses:

GET /api/v1/platform/oauth/logout#

Platform Logout

Platform-level OIDC End Session endpoint (RP-initiated logout).

Tenant-agnostic counterpart to /api/v1/auth/tenants/{slug}/oauth/logout — used by GLOBAL-scoped apps that don't have a tenant slug to put in the path. Resolves the SSO session by cookie and terminates it.

Parameters:

Responses:

POST /api/v1/platform/oauth/token#

Platform Token

Platform-level OAuth 2.0 Token endpoint.

Supports both authorization_code and client_credentials grants for GLOBAL-scoped applications.

Args: grant_type: "authorization_code" or "client_credentials" client_id: The application's client ID client_secret: The application's client secret code: Authorization code (for authorization_code grant) redirect_uri: Redirect URI (for authorization_code grant) code_verifier: PKCE code verifier (for authorization_code grant) scope: Requested scopes (for client_credentials grant) authorization: Basic auth header (alternative to client_id/secret in body)

Returns: TokenResponse with access_token

Parameters:

Request body:

Required.

• application/x-www-form-urlencoded → Body_platform_token_api_v1_platform_oauth_token_post

Responses:

GET /api/v1/platform/oauth/userinfo#

Platform Userinfo

Platform-level OIDC UserInfo endpoint.

Returns claims about the authenticated user.

Parameters:

Responses:

POST /api/v1/platform/oauth/userinfo#

Platform Userinfo

Platform-level OIDC UserInfo endpoint.

Returns claims about the authenticated user.

Parameters:

Responses:

Schemas#

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

Body_device_authorize_api_v1_platform_oauth_device_authorize_post#

Body_platform_token_api_v1_platform_oauth_token_post#

HTTPValidationError#

ValidationError#