The OpenID Connect (OIDC) API is a lightweight identity layer built on top of OAuth 2.0. It enables applications to verify user identity through the Authorization Code Flow, Implicit Flow, and Hybrid Flow. Key endpoints include the Authorization Endpoint, Token Endpoint, UserInfo Endpoint, and JWKS URI for token signature verification. OIDC is supported by all major identity providers.
openapi: 3.1.0
info:
title: OpenID Connect (OIDC) SSO API
description: >-
The OpenID Connect (OIDC) API is a lightweight identity layer built on top
of OAuth 2.0 that enables applications to verify user identity and obtain
basic profile information. OIDC defines standard endpoints including the
Authorization Endpoint, Token Endpoint, UserInfo Endpoint, and JWKS URI.
It supports Authorization Code Flow, Implicit Flow, Hybrid Flow, and PKCE
extensions for public clients. OIDC is widely implemented by identity
providers including Okta, Microsoft Entra ID, Google, Auth0, and Keycloak.
version: '1.0'
contact:
name: OpenID Foundation
url: https://openid.net/connect/
termsOfService: https://openid.net/connect/
externalDocs:
description: OpenID Connect Specification
url: https://openid.net/connect/
servers:
- url: https://your-idp.example.com
description: OpenID Provider (OP) Server
tags:
- name: Authorization
description: >-
OIDC authorization endpoints for initiating authentication flows and
exchanging authorization codes for tokens.
- name: Token
description: >-
Token endpoint operations for exchanging authorization codes and refresh
tokens for access tokens and ID tokens.
- name: User Info
description: >-
UserInfo endpoint for retrieving authenticated user profile claims.
- name: Discovery
description: >-
OpenID Provider Discovery endpoint for retrieving provider configuration
metadata.
- name: Keys
description: >-
JSON Web Key Set (JWKS) endpoint for retrieving public keys used to
verify ID token signatures.
paths:
/authorize:
get:
operationId: initiateOIDCAuthorization
summary: Initiate OIDC Authorization
description: >-
Initiates an OpenID Connect authorization flow. The client redirects
the user to this endpoint with the required parameters. On successful
authentication, the OpenID Provider redirects back to the client's
redirect_uri with an authorization code (Authorization Code Flow) or
tokens (Implicit Flow).
tags:
- Authorization
parameters:
- name: response_type
in: query
required: true
schema:
type: string
enum:
- code
- token
- id_token
- 'code token'
- 'code id_token'
- 'token id_token'
- 'code token id_token'
description: >-
Specifies the authorization flow. Use 'code' for Authorization
Code Flow, 'id_token' for Implicit Flow.
- name: client_id
in: query
required: true
schema:
type: string
description: The client identifier registered with the OpenID Provider
- name: redirect_uri
in: query
required: true
schema:
type: string
format: uri
description: >-
URI to redirect to after authentication. Must match a pre-registered
redirect URI for the client.
- name: scope
in: query
required: true
schema:
type: string
description: >-
Space-separated list of scopes. Must include 'openid'. Additional
scopes: profile, email, address, phone, offline_access.
example: 'openid profile email'
- name: state
in: query
required: true
schema:
type: string
description: >-
Opaque value used to maintain state between the request and callback.
Used to prevent CSRF attacks.
- name: nonce
in: query
schema:
type: string
description: >-
String value used to associate a client session with an ID token
and mitigate replay attacks.
- name: code_challenge
in: query
schema:
type: string
description: >-
PKCE code challenge derived from the code_verifier. Required for
public clients using PKCE.
- name: code_challenge_method
in: query
schema:
type: string
enum:
- S256
- plain
description: Method used to derive the code_challenge from code_verifier
- name: response_mode
in: query
schema:
type: string
enum:
- query
- fragment
- form_post
description: Mechanism used to return authorization response parameters
- name: prompt
in: query
schema:
type: string
enum:
- none
- login
- consent
- select_account
description: Prompts for user interaction during authentication
- name: login_hint
in: query
schema:
type: string
description: Hint to the authorization server about the login identifier
- name: acr_values
in: query
schema:
type: string
description: Authentication Context Class Reference values
responses:
'302':
description: Redirect to redirect_uri with authorization code or tokens
headers:
Location:
schema:
type: string
format: uri
description: >-
Redirect URL with code and state parameters (Authorization Code
Flow) or tokens in fragment (Implicit Flow)
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/token:
post:
operationId: exchangeToken
summary: Exchange Authorization Code for Tokens
description: >-
Exchanges an authorization code for an access token, ID token, and
optionally a refresh token. Also used to refresh expired access tokens
using a refresh token. Supports client_secret_basic and
client_secret_post authentication methods.
tags:
- Token
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
- client_credentials
description: The grant type for the token request
code:
type: string
description: >-
Authorization code received from the authorization endpoint.
Required for authorization_code grant.
redirect_uri:
type: string
format: uri
description: >-
Must match the redirect_uri used in the authorization request.
Required for authorization_code grant.
client_id:
type: string
description: >-
Client identifier. Required for client_secret_post
authentication.
client_secret:
type: string
description: >-
Client secret. Required for client_secret_post
authentication.
code_verifier:
type: string
description: >-
PKCE code verifier. Required when code_challenge was used
in the authorization request.
refresh_token:
type: string
description: >-
Refresh token for obtaining new access tokens. Required
for refresh_token grant.
scope:
type: string
description: >-
Optional scope for refresh_token grant. Must be a subset
of originally granted scopes.
responses:
'200':
description: Token response
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
description: Invalid token request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Client authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/userinfo:
get:
operationId: getUserInfo
summary: Get User Info
description: >-
Returns claims about the authenticated user. The access token is passed
as a Bearer token in the Authorization header. The claims returned
depend on the scopes granted during authorization.
tags:
- User Info
security:
- bearerAuth: []
responses:
'200':
description: User profile claims
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfoResponse'
'401':
description: Invalid or expired access token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: getUserInfoPost
summary: Get User Info (POST)
description: >-
Returns claims about the authenticated user via POST request. The
access token is passed as a Bearer token in the Authorization header.
tags:
- User Info
security:
- bearerAuth: []
responses:
'200':
description: User profile claims
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfoResponse'
'401':
description: Invalid or expired access token
/.well-known/openid-configuration:
get:
operationId: getOIDCDiscovery
summary: Get OpenID Provider Configuration
description: >-
Returns the OpenID Provider's configuration metadata as defined in
RFC 8414 (OAuth 2.0 Authorization Server Metadata) and the OIDC
Discovery specification. Clients use this endpoint to discover all
required endpoints, supported features, and public keys.
tags:
- Discovery
responses:
'200':
description: OpenID Provider configuration metadata
content:
application/json:
schema:
$ref: '#/components/schemas/OIDCConfiguration'
/jwks:
get:
operationId: getJWKS
summary: Get JSON Web Key Set
description: >-
Returns the JSON Web Key Set (JWKS) containing the public keys used
by the OpenID Provider to sign ID tokens and other JWTs. Clients use
these keys to verify the signature of ID tokens received from the
token endpoint.
tags:
- Keys
responses:
'200':
description: JSON Web Key Set
content:
application/json:
schema:
$ref: '#/components/schemas/JWKSResponse'
/revoke:
post:
operationId: revokeToken
summary: Revoke Token
description: >-
Revokes an access token or refresh token. The token is immediately
invalidated and can no longer be used for API access or token refresh.
tags:
- Token
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- token
properties:
token:
type: string
description: The access token or refresh token to revoke
token_type_hint:
type: string
enum:
- access_token
- refresh_token
description: Optional hint about the token type being revoked
client_id:
type: string
description: Client identifier
client_secret:
type: string
description: Client secret
responses:
'200':
description: Token successfully revoked (or was already invalid)
'400':
description: Invalid revocation request
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 Bearer access token in Authorization header
schemas:
TokenResponse:
type: object
required:
- access_token
- token_type
properties:
access_token:
type: string
description: OAuth 2.0 access token for API access
token_type:
type: string
enum:
- Bearer
description: Token type (always Bearer)
id_token:
type: string
description: >-
JWT-encoded ID token containing authenticated user claims. Present
for requests that included 'openid' scope.
refresh_token:
type: string
description: >-
Refresh token for obtaining new access tokens without re-
authentication. Present when offline_access scope was granted.
expires_in:
type: integer
description: Number of seconds until the access token expires
scope:
type: string
description: Space-separated list of scopes granted by the authorization server
UserInfoResponse:
type: object
properties:
sub:
type: string
description: Subject identifier - unique identifier for the user at the OP
name:
type: string
description: User's full name
given_name:
type: string
description: User's given (first) name
family_name:
type: string
description: User's family (last) name
middle_name:
type: string
description: User's middle name
nickname:
type: string
description: User's casual name
preferred_username:
type: string
description: Shorthand name for the user (username, handle)
profile:
type: string
format: uri
description: URL of the user's profile page
picture:
type: string
format: uri
description: URL of the user's profile picture
website:
type: string
format: uri
description: URL of the user's website
email:
type: string
format: email
description: User's email address
email_verified:
type: boolean
description: Whether the email has been verified
gender:
type: string
description: User's gender
birthdate:
type: string
description: User's birthdate in ISO 8601 format
zoneinfo:
type: string
description: User's time zone identifier
locale:
type: string
description: User's locale (BCP47 language tag)
phone_number:
type: string
description: User's phone number in E.164 format
phone_number_verified:
type: boolean
description: Whether the phone number has been verified
address:
type: object
description: User's address
properties:
formatted:
type: string
street_address:
type: string
locality:
type: string
region:
type: string
postal_code:
type: string
country:
type: string
updated_at:
type: integer
description: Unix timestamp of last profile update
OIDCConfiguration:
type: object
required:
- issuer
- authorization_endpoint
- token_endpoint
- jwks_uri
- response_types_supported
- subject_types_supported
- id_token_signing_alg_values_supported
properties:
issuer:
type: string
format: uri
description: URL of the OpenID Provider's issuer identifier
authorization_endpoint:
type: string
format: uri
description: URL of the authorization endpoint
token_endpoint:
type: string
format: uri
description: URL of the token endpoint
userinfo_endpoint:
type: string
format: uri
description: URL of the UserInfo endpoint
jwks_uri:
type: string
format: uri
description: URL of the JWKS endpoint
registration_endpoint:
type: string
format: uri
description: URL of the dynamic client registration endpoint
scopes_supported:
type: array
items:
type: string
description: Supported OAuth 2.0 scopes
response_types_supported:
type: array
items:
type: string
description: Supported OAuth 2.0 response types
grant_types_supported:
type: array
items:
type: string
description: Supported OAuth 2.0 grant types
subject_types_supported:
type: array
items:
type: string
description: Supported subject identifier types (public, pairwise)
id_token_signing_alg_values_supported:
type: array
items:
type: string
description: Supported JWS signing algorithms for ID tokens
token_endpoint_auth_methods_supported:
type: array
items:
type: string
description: Supported client authentication methods
claims_supported:
type: array
items:
type: string
description: Supported claims in ID tokens and UserInfo responses
code_challenge_methods_supported:
type: array
items:
type: string
description: Supported PKCE code challenge methods
revocation_endpoint:
type: string
format: uri
description: URL of the token revocation endpoint
JWKSResponse:
type: object
required:
- keys
properties:
keys:
type: array
items:
$ref: '#/components/schemas/JWK'
JWK:
type: object
description: JSON Web Key for verifying token signatures
required:
- kty
properties:
kty:
type: string
description: Key type (RSA, EC, oct)
example: RSA
use:
type: string
enum:
- sig
- enc
description: Intended use of the key
kid:
type: string
description: Key identifier
alg:
type: string
description: Algorithm intended for use with this key
example: RS256
n:
type: string
description: RSA modulus (base64url-encoded)
e:
type: string
description: RSA public exponent (base64url-encoded)
x5c:
type: array
items:
type: string
description: X.509 certificate chain
x5t:
type: string
description: X.509 certificate SHA-1 thumbprint
ErrorResponse:
type: object
required:
- error
properties:
error:
type: string
description: >-
Error code as defined in RFC 6749 (e.g., invalid_request,
invalid_client, invalid_grant, unauthorized_client,
unsupported_grant_type, invalid_scope)
error_description:
type: string
description: Human-readable error description
error_uri:
type: string
format: uri
description: URI of a web page with more information about the error