---
title: Platform OAuth API
path: reference/api/platform-oauth
status: published
---

# 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](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/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:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |

---

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

_Platform Openid Configuration_

Platform-level OpenID Configuration.

Returns minimal configuration for platform-level OAuth.

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |

---

### **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:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `response_type` | query | yes | `string` |  |
| `client_id` | query | yes | `string` |  |
| `redirect_uri` | query | yes | `string` |  |
| `scope` | query | yes | `string` |  |
| `state` | query | no | `string` \| `null` |  |
| `nonce` | query | no | `string` \| `null` |  |
| `code_challenge` | query | no | `string` \| `null` |  |
| `code_challenge_method` | query | no | `string` \| `null` |  |
| `prompt` | query | no | `string` \| `null` |  |
| `login_hint` | query | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **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:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_device_authorize_api_v1_platform_oauth_device_authorize_post`](#schema-body-device-authorize-api-v1-platform-oauth-device-authorize-post)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **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:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `user_code` | query | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **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:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |

---

### **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:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id_token_hint` | query | no | `string` \| `null` |  |
| `post_logout_redirect_uri` | query | no | `string` \| `null` |  |
| `state` | query | no | `string` \| `null` |  |
| `client_id` | query | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **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:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_platform_token_api_v1_platform_oauth_token_post`](#schema-body-platform-token-api-v1-platform-oauth-token-post)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

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

_Platform Userinfo_

Platform-level OIDC UserInfo endpoint.

Returns claims about the authenticated user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

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

_Platform Userinfo_

Platform-level OIDC UserInfo endpoint.

Returns claims about the authenticated user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## 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`

| Field | Type | Required | Description |
|---|---|---|---|
| `client_id` | `string` | yes |  |
| `scope` | `string` | no | Default: `openid` |

### `Body_platform_token_api_v1_platform_oauth_token_post`

| Field | Type | Required | Description |
|---|---|---|---|
| `grant_type` | `string` | yes |  |
| `client_id` | `string` \| `null` | no |  |
| `client_secret` | `string` \| `null` | no |  |
| `code` | `string` \| `null` | no |  |
| `device_code` | `string` \| `null` | no |  |
| `refresh_token` | `string` \| `null` | no |  |
| `redirect_uri` | `string` \| `null` | no |  |
| `code_verifier` | `string` \| `null` | no |  |
| `scope` | `string` \| `null` | no |  |
| `subject_token` | `string` \| `null` | no |  |
| `subject_token_type` | `string` \| `null` | no |  |
| `audience` | `string` \| `null` | no |  |
| `requested_token_type` | `string` \| `null` | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |