OpenID Connect API

openapi: 3.1.0
info:
  title: OpenID Connect API
  description: >-
    OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0
    protocol. It allows clients to verify the identity of end-users based on
    the authentication performed by an authorization server, and to obtain
    basic profile information about the end-user in an interoperable and
    REST-like manner. This specification covers the core OIDC endpoints
    including discovery, token, userinfo, and JWKS.
  version: '1.0'
  contact:
    name: OpenID Foundation
    url: https://openid.net/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://{issuer}
    description: OpenID Connect Provider
    variables:
      issuer:
        default: example.com
        description: The OIDC issuer domain
paths:
  /.well-known/openid-configuration:
    get:
      operationId: getDiscovery
      summary: OpenID Connect Discovery
      description: >-
        Returns the OpenID Provider Configuration Information document,
        which contains metadata about the OpenID Provider including its
        issuer, supported endpoints, scopes, response types, and other
        capabilities.
      tags:
        - Discovery
      responses:
        '200':
          description: OpenID Provider Configuration Information
          content:
            application/json:
              schema:
                $ref: '../json-schema/oidc-discovery.json'
  /authorize:
    get:
      operationId: authorize
      summary: Authorization Endpoint
      description: >-
        Performs authentication of the end-user. The authorization endpoint
        is used to interact with the resource owner and obtain an
        authorization grant. The endpoint handles the authentication flow
        and redirects back to the client with an authorization code or
        tokens depending on the response type.
      tags:
        - Authentication
      parameters:
        - name: response_type
          in: query
          required: true
          description: >-
            The value must include 'code' for the Authorization Code Flow,
            'id_token' for the Implicit Flow, or 'code id_token' for the
            Hybrid Flow.
          schema:
            type: string
            enum:
              - code
              - id_token
              - id_token token
              - code id_token
              - code token
              - code id_token token
        - name: client_id
          in: query
          required: true
          description: The client identifier issued during registration.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: >-
            The redirection URI to which the response will be sent. Must
            exactly match one of the redirection URIs registered for the
            client.
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: true
          description: >-
            Space-delimited list of scopes. Must include 'openid' to
            indicate an OIDC request. May also include 'profile', 'email',
            'address', and 'phone'.
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: >-
            An opaque value used by the client to maintain state between
            the request and callback. Recommended for CSRF protection.
          schema:
            type: string
        - name: nonce
          in: query
          required: false
          description: >-
            A string value used to associate a client session with an ID
            Token and to mitigate replay attacks. Required for implicit
            flow.
          schema:
            type: string
        - name: prompt
          in: query
          required: false
          description: >-
            Space-delimited list of values that specifies whether the
            authorization server prompts the end-user for reauthentication
            and consent.
          schema:
            type: string
            enum:
              - none
              - login
              - consent
              - select_account
        - name: login_hint
          in: query
          required: false
          description: >-
            A hint to the authorization server about the login identifier
            the end-user might use.
          schema:
            type: string
        - name: acr_values
          in: query
          required: false
          description: >-
            Requested Authentication Context Class Reference values.
          schema:
            type: string
        - name: code_challenge
          in: query
          required: false
          description: >-
            PKCE code challenge derived from the code verifier.
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: false
          description: Code challenge method used to derive the code challenge.
          schema:
            type: string
            enum:
              - plain
              - S256
      responses:
        '302':
          description: >-
            Redirect to the client redirect_uri with authorization code
            or tokens in the query string or fragment.
        '400':
          description: Invalid request parameters.
        '401':
          description: Authentication failed.
  /token:
    post:
      operationId: getToken
      summary: Token Endpoint
      description: >-
        Exchanges an authorization code, refresh token, or client
        credentials for an access token and optionally a refresh token
        and ID token. The token endpoint is used by the client to obtain
        tokens after receiving an authorization code from the
        authorization endpoint.
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
              properties:
                grant_type:
                  type: string
                  description: The type of grant being presented.
                  enum:
                    - authorization_code
                    - refresh_token
                    - client_credentials
                code:
                  type: string
                  description: The authorization code received from the authorization endpoint.
                redirect_uri:
                  type: string
                  format: uri
                  description: The redirect URI used in the authorization request.
                client_id:
                  type: string
                  description: The client identifier.
                client_secret:
                  type: string
                  description: The client secret.
                refresh_token:
                  type: string
                  description: The refresh token for obtaining a new access token.
                scope:
                  type: string
                  description: The requested scope.
                code_verifier:
                  type: string
                  description: PKCE code verifier that was used to generate the code challenge.
      responses:
        '200':
          description: Successful token response containing access token and optionally ID token.
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                  - token_type
                properties:
                  access_token:
                    type: string
                    description: The access token issued by the authorization server.
                  token_type:
                    type: string
                    description: The type of token issued, typically 'Bearer'.
                    enum:
                      - Bearer
                  expires_in:
                    type: integer
                    description: The lifetime in seconds of the access token.
                  refresh_token:
                    type: string
                    description: A refresh token that can be used to obtain new access tokens.
                  id_token:
                    type: string
                    description: >-
                      A JSON Web Token (JWT) that contains claims about the
                      authentication event and the end-user.
                  scope:
                    type: string
                    description: The scope of the access token.
        '400':
          description: Invalid request, such as an invalid grant or unauthorized client.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - invalid_client
                      - invalid_grant
                      - unauthorized_client
                      - unsupported_grant_type
                      - invalid_scope
                  error_description:
                    type: string
  /userinfo:
    get:
      operationId: getUserInfo
      summary: UserInfo Endpoint
      description: >-
        Returns claims about the authenticated end-user. The caller must
        present a valid access token obtained through OIDC authentication.
        The claims returned depend on the scopes granted during
        authorization.
      tags:
        - UserInfo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Claims about the authenticated end-user.
          content:
            application/json:
              schema:
                $ref: '../json-schema/oidc-userinfo-response.json'
        '401':
          description: Missing or invalid access token.
        '403':
          description: Insufficient scope for the requested claims.
    post:
      operationId: postUserInfo
      summary: UserInfo Endpoint (POST)
      description: >-
        Returns claims about the authenticated end-user using a POST
        request. Functionally identical to the GET variant.
      tags:
        - UserInfo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Claims about the authenticated end-user.
          content:
            application/json:
              schema:
                $ref: '../json-schema/oidc-userinfo-response.json'
        '401':
          description: Missing or invalid access token.
        '403':
          description: Insufficient scope for the requested claims.
  /.well-known/jwks.json:
    get:
      operationId: getJwks
      summary: JSON Web Key Set Endpoint
      description: >-
        Returns the JSON Web Key Set (JWKS) containing the public keys
        used by the OpenID Provider to sign tokens. Clients use these
        keys to verify the signatures of ID tokens and other signed
        artifacts.
      tags:
        - JWKS
      responses:
        '200':
          description: JSON Web Key Set containing the provider's public keys.
          content:
            application/json:
              schema:
                type: object
                required:
                  - keys
                properties:
                  keys:
                    type: array
                    description: Array of JSON Web Key objects.
                    items:
                      type: object
                      required:
                        - kty
                        - use
                        - kid
                      properties:
                        kty:
                          type: string
                          description: The key type (e.g., RSA, EC).
                        use:
                          type: string
                          description: The intended use of the key (sig or enc).
                          enum:
                            - sig
                            - enc
                        kid:
                          type: string
                          description: A unique identifier for the key.
                        alg:
                          type: string
                          description: The algorithm intended for use with the key.
                        n:
                          type: string
                          description: The modulus value for an RSA public key (Base64urlUInt-encoded).
                        e:
                          type: string
                          description: The exponent value for an RSA public key (Base64urlUInt-encoded).
                        x:
                          type: string
                          description: The x coordinate for an EC public key.
                        'y':
                          type: string
                          description: The y coordinate for an EC public key.
                        crv:
                          type: string
                          description: The curve for an EC key.
                        x5c:
                          type: array
                          description: X.509 certificate chain.
                          items:
                            type: string
                        x5t:
                          type: string
                          description: X.509 certificate SHA-1 thumbprint.
  /end-session:
    get:
      operationId: endSession
      summary: End Session Endpoint
      description: >-
        Initiates the logout process. The end-user is redirected to this
        endpoint to log out of the OpenID Provider. Supports RP-Initiated
        Logout as defined in the OIDC Session Management specification.
      tags:
        - Session
      parameters:
        - name: id_token_hint
          in: query
          required: false
          description: The ID token previously issued to the client.
          schema:
            type: string
        - name: post_logout_redirect_uri
          in: query
          required: false
          description: The URI to redirect to after logout.
          schema:
            type: string
            format: uri
        - name: state
          in: query
          required: false
          description: Opaque value for maintaining state between request and callback.
          schema:
            type: string
      responses:
        '302':
          description: Redirect to the post-logout redirect URI or a default page.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer Token obtained through OIDC authentication.
tags:
  - name: Discovery
    description: OpenID Connect Discovery endpoints for provider metadata.
  - name: Authentication
    description: Endpoints for authenticating end-users and obtaining authorization grants.
  - name: Token
    description: Token endpoint for exchanging authorization codes for tokens.
  - name: UserInfo
    description: Endpoint for retrieving claims about the authenticated end-user.
  - name: JWKS
    description: JSON Web Key Set endpoint for token signature verification.
  - name: Session
    description: Session management endpoints including logout.