---
title: OIDC API
path: reference/api/oidc
status: published
---

# OIDC API

Reference for the `OIDC` endpoint group — 11 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/auth/tenants/{tenant_slug}/.well-known/jwks.json`

_Jwks_

JSON Web Key Set endpoint.

Returns the public keys used to verify token signatures.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |

**Responses:**

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

---

### **GET** `/api/v1/auth/tenants/{tenant_slug}/.well-known/openid-configuration`

_Openid Configuration_

OpenID Connect Discovery endpoint.

Returns the OpenID Provider configuration for the tenant.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/backchannel-logout`

_Backchannel Logout_

OIDC Back-Channel Logout endpoint.

Receives logout notifications from external IdPs when ScaiKey acts as a
Relying Party (SP). Per OIDC Back-Channel Logout specification.

The logout_token is a JWT containing:
- iss: Issuer (the IdP sending the logout)
- sub: User ID to logout (optional if sid present)
- aud: ScaiKey's client_id at the IdP
- iat: Issued at time
- jti: Unique identifier for the token
- events: Must contain "http://schemas.openid.net/event/backchannel-logout": {}
- sid: Session ID to terminate (optional if sub present)

Returns:
    200 OK: Logout processed successfully
    400 Bad Request: Invalid logout token

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_backchannel_logout_api_v1_auth_tenants__tenant_slug__backchannel_logout_post`](#schema-body-backchannel-logout-api-v1-auth-tenants-tenant-slug-backchannel-logout-post)

**Responses:**

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

---

### **GET** `/api/v1/auth/tenants/{tenant_slug}/oauth/authorize`

_Authorize_

OAuth 2.0 Authorization endpoint.

Initiates the authorization flow by redirecting to the login page.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |
| `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` |  |
| `acr_values` | query | no | `string` \| `null` |  |
| `idp_hint` | query | no | `string` \| `null` |  |

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/oauth/authorize/complete`

_Authorize Complete_

Complete OAuth 2.0 Authorization.

Called after successful login/consent to issue the authorization code.
Returns the authorization code that can be exchanged for tokens.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`AuthorizeCompleteRequest`](#schema-authorizecompleterequest)

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/oauth/introspect`

_Introspect_

OAuth 2.0 Token Introspection endpoint.

Introspects a token to determine its validity and claims.

**Parameters:**

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

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_introspect_api_v1_auth_tenants__tenant_slug__oauth_introspect_post`](#schema-body-introspect-api-v1-auth-tenants-tenant-slug-oauth-introspect-post)

**Responses:**

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

---

### **GET** `/api/v1/auth/tenants/{tenant_slug}/oauth/logout`

_Logout_

OIDC End Session endpoint.

Initiates Single Logout (SLO).

**Parameters:**

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

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/oauth/revoke`

_Revoke_

OAuth 2.0 Token Revocation endpoint.

Revokes a refresh token or access token.

**Parameters:**

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

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_revoke_api_v1_auth_tenants__tenant_slug__oauth_revoke_post`](#schema-body-revoke-api-v1-auth-tenants-tenant-slug-oauth-revoke-post)

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/oauth/token`

_Token_

OAuth 2.0 Token endpoint.

Exchanges authorization code for tokens, refreshes tokens,
or performs token exchange (RFC 8693).

**Parameters:**

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

**Request body:**

Required.

- `application/x-www-form-urlencoded` → [`Body_token_api_v1_auth_tenants__tenant_slug__oauth_token_post`](#schema-body-token-api-v1-auth-tenants-tenant-slug-oauth-token-post)

**Responses:**

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

---

### **GET** `/api/v1/auth/tenants/{tenant_slug}/oauth/userinfo`

_Userinfo_

OIDC UserInfo endpoint.

Returns claims about the authenticated user.

**Parameters:**

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

**Responses:**

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

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/oauth/userinfo`

_Userinfo_

OIDC UserInfo endpoint.

Returns claims about the authenticated user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |
| `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.

### `AuthorizeCompleteRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `session_id` | `string` | yes |  |
| `client_id` | `string` | yes |  |
| `redirect_uri` | `string` | yes |  |
| `scope` | `string` | yes |  |
| `response_type` | `string` | yes |  |
| `state` | `string` \| `null` | no |  |
| `nonce` | `string` \| `null` | no |  |
| `code_challenge` | `string` \| `null` | no |  |
| `code_challenge_method` | `string` \| `null` | no |  |

### `Body_backchannel_logout_api_v1_auth_tenants__tenant_slug__backchannel_logout_post`

| Field | Type | Required | Description |
|---|---|---|---|
| `logout_token` | `string` | yes |  |

### `Body_introspect_api_v1_auth_tenants__tenant_slug__oauth_introspect_post`

| Field | Type | Required | Description |
|---|---|---|---|
| `token` | `string` | yes |  |
| `token_type_hint` | `string` \| `null` | no |  |
| `client_id` | `string` \| `null` | no |  |
| `client_secret` | `string` \| `null` | no |  |

### `Body_revoke_api_v1_auth_tenants__tenant_slug__oauth_revoke_post`

| Field | Type | Required | Description |
|---|---|---|---|
| `token` | `string` | yes |  |
| `token_type_hint` | `string` \| `null` | no |  |
| `client_id` | `string` \| `null` | no |  |
| `client_secret` | `string` \| `null` | no |  |

### `Body_token_api_v1_auth_tenants__tenant_slug__oauth_token_post`

| Field | Type | Required | Description |
|---|---|---|---|
| `grant_type` | `string` | yes |  |
| `code` | `string` \| `null` | no |  |
| `redirect_uri` | `string` \| `null` | no |  |
| `refresh_token` | `string` \| `null` | no |  |
| `client_id` | `string` \| `null` | no |  |
| `client_secret` | `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 |  |

### `OpenIDConfiguration`

OpenID Connect Discovery document.

| Field | Type | Required | Description |
|---|---|---|---|
| `issuer` | `string` | yes |  |
| `authorization_endpoint` | `string` | yes |  |
| `token_endpoint` | `string` | yes |  |
| `userinfo_endpoint` | `string` | yes |  |
| `jwks_uri` | `string` | yes |  |
| `end_session_endpoint` | `string` | yes |  |
| `revocation_endpoint` | `string` | yes |  |
| `introspection_endpoint` | `string` | yes |  |
| `scopes_supported` | array of `string` | yes |  |
| `response_types_supported` | array of `string` | yes |  |
| `response_modes_supported` | array of `string` | yes |  |
| `grant_types_supported` | array of `string` | yes |  |
| `subject_types_supported` | array of `string` | yes |  |
| `id_token_signing_alg_values_supported` | array of `string` | yes |  |
| `token_endpoint_auth_methods_supported` | array of `string` | yes |  |
| `claims_supported` | array of `string` | yes |  |
| `code_challenge_methods_supported` | array of `string` | yes |  |
| `backchannel_logout_supported` | `boolean` | no | Default: `True` |
| `backchannel_logout_session_supported` | `boolean` | no | Default: `True` |
| `backchannel_logout_uri` | `string` \| `null` | no |  |

### `TokenIntrospectionResponse`

Token introspection response.

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | yes |  |
| `sub` | `string` \| `null` | no |  |
| `client_id` | `string` \| `null` | no |  |
| `scope` | `string` \| `null` | no |  |
| `exp` | `integer` \| `null` | no |  |
| `iat` | `integer` \| `null` | no |  |
| `iss` | `string` \| `null` | no |  |
| `aud` | `string` \| `null` | no |  |
| `token_type` | `string` \| `null` | no |  |
| `tenant_id` | `string` \| `null` | no |  |
| `email` | `string` \| `null` | no |  |
| `groups` | array of `string` \| `null` | no |  |

### `ValidationError`

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