openapi: 3.0.3
info:
  title: OAuth 2.0 Server Authorization Token API
  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: Token
  description: OAuth 2.0 token endpoint operations.
paths:
  /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: []
      - {}
components:
  schemas:
    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.
    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.
  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.