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

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`
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `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
`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`

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

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → `TokenIntrospectionResponse`
`422`	`application/json` → `HTTPValidationError`

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

Logout

OIDC End Session endpoint.

Initiates Single Logout (SLO).

Parameters:

Name	In	Required	Type
`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`

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

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → any
`422`	`application/json` → `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`

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`

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
`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
`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
`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
`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`	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
`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
`loc`	array of `string` \| `integer`	yes
`msg`	`string`	yes
`type`	`string`	yes

OIDC API

Authentication#

Endpoints#

GET /api/v1/auth/tenants/{tenant_slug}/.well-known/jwks.json#

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

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

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

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

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

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

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

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

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

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

Schemas#

AuthorizeCompleteRequest#

Body_backchannel_logout_api_v1_auth_tenants__tenant_slug__backchannel_logout_post#

Body_introspect_api_v1_auth_tenants__tenant_slug__oauth_introspect_post#

Body_revoke_api_v1_auth_tenants__tenant_slug__oauth_revoke_post#

Body_token_api_v1_auth_tenants__tenant_slug__oauth_token_post#

HTTPValidationError#

OpenIDConfiguration#

TokenIntrospectionResponse#

ValidationError#

GET `/api/v1/auth/tenants/{tenant_slug}/.well-known/jwks.json`#

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

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

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

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

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

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

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

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

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

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

`AuthorizeCompleteRequest`#

`Body_backchannel_logout_api_v1_auth_tenants__tenant_slug__backchannel_logout_post`#

`Body_introspect_api_v1_auth_tenants__tenant_slug__oauth_introspect_post`#

`Body_revoke_api_v1_auth_tenants__tenant_slug__oauth_revoke_post`#

`Body_token_api_v1_auth_tenants__tenant_slug__oauth_token_post`#

`HTTPValidationError`#

`OpenIDConfiguration`#

`TokenIntrospectionResponse`#

`ValidationError`#