openapi: 3.0.3
info:
  title: OAuth 2.0 Authorization Server
  description: >-
    OpenAPI specification for OAuth 2.0 authorization server endpoints as
    defined in RFC 6749 (The OAuth 2.0 Authorization Framework) and RFC 6750
    (Bearer Token Usage). Covers the token endpoint, authorization endpoint,
    and token revocation endpoint (RFC 7009).
  version: 1.0.0
  contact:
    name: Kin Lane
    email: info@apievangelist.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://authorization-server.example.com
    description: OAuth 2.0 Authorization Server
tags:
  - name: Authorization
    description: OAuth 2.0 authorization endpoint operations.
  - name: Token
    description: OAuth 2.0 token endpoint operations.
  - name: Revocation
    description: OAuth 2.0 token revocation operations (RFC 7009).
paths:
  /authorize:
    get:
      operationId: authorize
      summary: Authorization Endpoint
      description: >-
        The authorization endpoint is used to interact with the resource owner
        and obtain an authorization grant. The authorization server MUST first
        verify the identity of the resource owner.
      tags:
        - Authorization
      parameters:
        - name: response_type
          in: query
          required: true
          description: >-
            The value MUST be "code" for requesting an authorization code or
            "token" for requesting an access token (implicit grant).
          schema:
            type: string
            enum:
              - code
              - token
        - name: client_id
          in: query
          required: true
          description: The client identifier issued to the client during registration.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: false
          description: >-
            The URI to which the authorization server will redirect the
            user-agent after authorization is granted or denied.
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: false
          description: The scope of the access request as a space-delimited list of values.
          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. Used to prevent cross-site request forgery.
          schema:
            type: string
      responses:
        "302":
          description: >-
            Redirect to the client redirect_uri with authorization code or
            access token appended as query or fragment parameters.
          headers:
            Location:
              description: Redirect URI with authorization response parameters.
              schema:
                type: string
                format: uri
        "400":
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Client authentication failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /token:
    post:
      operationId: requestToken
      summary: Token Endpoint
      description: >-
        The token endpoint is used by the client to obtain an access token by
        presenting its authorization grant or refresh token. Supports
        authorization code, client credentials, resource owner password
        credentials, and refresh token grant types.
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenRequest"
            examples:
              AuthorizationCode:
                summary: Authorization Code Grant
                value:
                  grant_type: authorization_code
                  code: SplxlOBeZQQYbYS6WxSbIA
                  redirect_uri: https://client.example.org/callback
                  client_id: s6BhdRkqt3
              ClientCredentials:
                summary: Client Credentials Grant
                value:
                  grant_type: client_credentials
                  scope: read write
              RefreshToken:
                summary: Refresh Token Grant
                value:
                  grant_type: refresh_token
                  refresh_token: tGzv3JOkF0XG5Qx2TlKWIA
              ResourceOwnerPassword:
                summary: Resource Owner Password Credentials Grant
                value:
                  grant_type: password
                  username: johndoe
                  password: A3ddj3w
                  scope: read
      responses:
        "200":
          description: Successful token response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
              example:
                access_token: 2YotnFZFEjr1zCsicMWpAA
                token_type: Bearer
                expires_in: 3600
                refresh_token: tGzv3JOkF0XG5Qx2TlKWIA
                scope: read write
          headers:
            Cache-Control:
              description: MUST be set to no-store.
              schema:
                type: string
                example: no-store
            Pragma:
              description: MUST be set to no-cache.
              schema:
                type: string
                example: no-cache
        "400":
          description: Error response for invalid token requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: invalid_grant
                error_description: The authorization code has expired.
        "401":
          description: Client authentication failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - ClientBasicAuth: []
        - {}
  /revoke:
    post:
      operationId: revokeToken
      summary: Token Revocation Endpoint
      description: >-
        The token revocation endpoint allows clients to notify the
        authorization server that a previously obtained token is no longer
        needed, as defined in RFC 7009.
      tags:
        - Revocation
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                  description: The token that the client wants to have revoked.
                token_type_hint:
                  type: string
                  description: A hint about the type of the token being revoked.
                  enum:
                    - access_token
                    - refresh_token
      responses:
        "200":
          description: >-
            The authorization server responds with HTTP status code 200 for
            both successful and unsuccessful revocation requests.
        "400":
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Client authentication failed.
      security:
        - ClientBasicAuth: []
components:
  securitySchemes:
    ClientBasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using the client_id as username and
        client_secret as password, as defined in RFC 6749 Section 2.3.1.
  schemas:
    TokenRequest:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          type: string
          description: The type of grant being presented.
          enum:
            - authorization_code
            - client_credentials
            - password
            - refresh_token
        code:
          type: string
          description: The authorization code received from the authorization server. Required for authorization_code grant type.
        redirect_uri:
          type: string
          format: uri
          description: The redirect URI used in the authorization request. Required if included in the original authorization request.
        client_id:
          type: string
          description: The client identifier. Required for public clients not authenticating via other means.
        client_secret:
          type: string
          description: The client secret. Used for confidential clients authenticating via POST body.
        scope:
          type: string
          description: The scope of the access request as a space-delimited list.
        username:
          type: string
          description: The resource owner username. Required for password grant type.
        password:
          type: string
          description: The resource owner password. Required for password grant type.
        refresh_token:
          type: string
          description: The refresh token. Required for refresh_token grant type.
    TokenResponse:
      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 the token issued (e.g., Bearer).
          example: Bearer
        expires_in:
          type: integer
          description: The lifetime in seconds of the access token.
          example: 3600
        refresh_token:
          type: string
          description: A refresh token that can be used to obtain new access tokens.
        scope:
          type: string
          description: The scope of the access token as a space-delimited list.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A single ASCII error code from the defined set.
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - invalid_scope
            - unsupported_token_type
        error_description:
          type: string
          description: A human-readable description providing additional information about the error.
        error_uri:
          type: string
          format: uri
          description: A URI identifying a human-readable web page with information about the error.