openapi: 3.0.3
info:
  title: Spring Authorization Server API
  description: >-
    Spring Authorization Server is a framework providing implementations of
    OAuth 2.1 and OpenID Connect 1.0 specifications. It exposes standard
    protocol endpoints for token issuance, token introspection, JWKS publication,
    device authorization, and OpenID Connect session management.
  version: 1.3.0
  contact:
    name: Spring Security Team
    url: https://spring.io/projects/spring-authorization-server
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:9000
    description: Default authorization server port
paths:
  /oauth2/authorize:
    get:
      operationId: authorizationRequest
      summary: OAuth2 Authorization Request
      description: Initiates the OAuth 2.1 authorization code flow with PKCE
      tags:
        - Authorization
      parameters:
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
        - name: code_challenge
          in: query
          schema:
            type: string
        - name: code_challenge_method
          in: query
          schema:
            type: string
            enum: [S256]
      responses:
        '302':
          description: Redirect to login or consent
  /oauth2/token:
    post:
      operationId: tokenRequest
      summary: OAuth2 Token Request
      description: Issues access tokens for all supported grant types
      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
                    - urn:ietf:params:oauth:grant-type:device_code
                    - urn:ietf:params:oauth:grant-type:token-exchange
                code:
                  type: string
                redirect_uri:
                  type: string
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                scope:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
      security:
        - basicAuth: []
        - {}
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Token error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
  /oauth2/introspect:
    post:
      operationId: tokenIntrospection
      summary: Token Introspection
      description: Validates tokens and returns active token metadata per RFC 7662
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
      security:
        - basicAuth: []
      responses:
        '200':
          description: Introspection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
  /oauth2/revoke:
    post:
      operationId: tokenRevocation
      summary: Token Revocation
      description: Revokes access or refresh tokens per RFC 7009
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
      security:
        - basicAuth: []
      responses:
        '200':
          description: Token revoked
  /oauth2/jwks:
    get:
      operationId: getJwks
      summary: JSON Web Key Set
      description: Returns public signing keys for JWT verification
      tags:
        - Keys
      responses:
        '200':
          description: JWKS document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwksResponse'
  /oauth2/device_authorization:
    post:
      operationId: deviceAuthorization
      summary: Device Authorization Request
      description: Initiates the OAuth 2.0 Device Authorization Grant per RFC 8628
      tags:
        - Device
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                scope:
                  type: string
      security:
        - basicAuth: []
      responses:
        '200':
          description: Device authorization response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
  /connect/register:
    post:
      operationId: registerClient
      summary: Dynamic Client Registration
      description: Registers a new OAuth2 client dynamically per RFC 7591
      tags:
        - Client Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRegistrationRequest'
      responses:
        '201':
          description: Client registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRegistrationResponse'
        '400':
          description: Invalid registration request
  /userinfo:
    get:
      operationId: getUserInfo
      summary: OpenID Connect UserInfo
      description: Returns claims about the authenticated end-user
      tags:
        - OpenID Connect
      security:
        - bearerAuth: []
      responses:
        '200':
          description: UserInfo claims
          content:
            application/json:
              schema:
                type: object
  /.well-known/openid-configuration:
    get:
      operationId: getOidcDiscovery
      summary: OpenID Connect Discovery
      description: Returns authorization server OIDC metadata
      tags:
        - Discovery
      responses:
        '200':
          description: OIDC configuration
          content:
            application/json:
              schema:
                type: object
  /.well-known/oauth-authorization-server:
    get:
      operationId: getOAuthMetadata
      summary: OAuth2 Server Metadata
      description: Returns RFC 8414 authorization server metadata
      tags:
        - Discovery
      responses:
        '200':
          description: Server metadata
          content:
            application/json:
              schema:
                type: object
  /connect/logout:
    get:
      operationId: oidcLogout
      summary: OpenID Connect Session Logout
      description: Initiates OIDC RP-initiated logout
      tags:
        - OpenID Connect
      parameters:
        - name: id_token_hint
          in: query
          schema:
            type: string
        - name: post_logout_redirect_uri
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
      responses:
        '302':
          description: Redirect after logout
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token:
          type: string
        scope:
          type: string
        id_token:
          type: string
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    IntrospectionResponse:
      type: object
      properties:
        active:
          type: boolean
        scope:
          type: string
        client_id:
          type: string
        username:
          type: string
        token_type:
          type: string
        exp:
          type: integer
        sub:
          type: string
    JwksResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: object
    DeviceAuthorizationResponse:
      type: object
      properties:
        device_code:
          type: string
        user_code:
          type: string
        verification_uri:
          type: string
        verification_uri_complete:
          type: string
        expires_in:
          type: integer
        interval:
          type: integer
    ClientRegistrationRequest:
      type: object
      properties:
        client_name:
          type: string
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            type: string
        response_types:
          type: array
          items:
            type: string
        scope:
          type: string
        token_endpoint_auth_method:
          type: string
        logo_uri:
          type: string
    ClientRegistrationResponse:
      type: object
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        client_name:
          type: string
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            type: string
        registration_access_token:
          type: string
        registration_client_uri:
          type: string
tags:
  - name: Authorization
  - name: Client Management
  - name: Device
  - name: Discovery
  - name: Keys
  - name: OpenID Connect
  - name: Token