oauth2_endpoints.yml

openapi: '3.0.2'
info:
  title: OAuth2 Token Endpoint Components
  version: '1.0'
  description: |-
    This document omits authorization endpoint on purpose. I don't know how to describe it with OAS3 since endpoint response isn't JSON(html page). If you have any suggestion please submit an issue to this repo.

    Quote from [RFC 6749 - The OAuth2.0 Authorization Framework - 2.3.1. Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1):

    > Including the client credentials in the request-body using the two parameters is **NOT RECOMMENDED** and **SHOULD** be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes).
    > The parameters can only be transmitted in the request-body and **MUST NOT** be included in the request URI.
servers:
  - url: https://server.example.com/
paths:
  /code/token:
    post:
      tags:
        - OAuth2
      summary: Obtain access token with "authorization_code" grant.
      externalDocs:
        description: RFC 6749 - The OAuth2.0 Authorization Framework
        url: https://tools.ietf.org/html/rfc6749#section-4.1.3
      operationId: obtainAccessTokenViaCodeGrant
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestCodeGrant'
      responses:
        '200':
          $ref: '#/components/responses/OAuth2TokenSuccessResponse'
        '4XX':
          $ref: '#/components/responses/OAuth2TokenErrorResponse'
      security:
        - ClientPasswordHttpBasic: []
  /password/token:
    post:
      tags:
        - OAuth2
      summary: Obtain access token with "password" grant.
      externalDocs:
        description: RFC 6749 - The OAuth2.0 Authorization Framework
        url: https://tools.ietf.org/html/rfc6749#section-4.3.2
      operationId: obtainAccessTokenViaPasswordGrant
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestPasswordGrant'
      responses:
        '200':
          $ref: '#/components/responses/OAuth2TokenSuccessResponse'
        '4XX':
          $ref: '#/components/responses/OAuth2TokenErrorResponse'
      security:
        - ClientPasswordHttpBasic: []
  /client/token:
    post:
      tags:
        - OAuth2
      summary: Obtain access token with "client_credentials" grant.
      externalDocs:
        description: RFC 6749 - The OAuth2.0 Authorization Framework
        url: https://tools.ietf.org/html/rfc6749#section-4.4.2
      operationId: obtainAccessTokenViaClientCredentialsGrant
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestClientCredentialsGrant'
      responses:
        '200':
          $ref: '#/components/responses/OAuth2TokenSuccessResponse'
        '4XX':
          $ref: '#/components/responses/OAuth2TokenErrorResponse'
      security:
        - ClientPasswordHttpBasic: []
  /refresh/token:
    post:
      tags:
        - OAuth2
      summary: Refresh access token.
      externalDocs:
        description: RFC 6749 - The OAuth2.0 Authorization Framework
        url: https://tools.ietf.org/html/rfc6749#section-6
      operationId: obtainAccessTokenViaRefreshGrant
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestRefreshGrant'
      responses:
        '200':
          $ref: '#/components/responses/OAuth2TokenSuccessResponse'
        '4XX':
          $ref: '#/components/responses/OAuth2TokenErrorResponse'
      security:
        - ClientPasswordHttpBasic: []
components:
  schemas:
    Token:
      title: Token
      description: |-
        Access Token

        [The OAuth2.0 Authorization Framework - 1.4. Access Token](https://tools.ietf.org/html/rfc6749#section-1.4)

        Access tokens are credentials used to access protected resources.  An access token is a string representing an authorization issued to the client.  The string is usually opaque to the client.  Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          description: |-
            The access token issued by the authorization server.
          type: string
          example: 2YotnFZFEjr1zCsicMWpAA
        token_type:
          description: |-
            The type of the token issued as described in [Section 7.1](https://tools.ietf.org/html/rfc6749#section-7.1).  Value is case insensitive.
          type: string
          example: Bearer
        expires_in:
          description: |-
            **RECOMMENDED**. The lifetime in seconds of the access token.  For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
          type: integer
          example: 3600
        refresh_token:
          description: |-
            The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in [Section 6](https://tools.ietf.org/html/rfc6749#section-6).
          type: string
          example: tGzv3JOkF0XG5Qx2TlKWIA
        scope:
          description: |-
            **OPTIONAL**, if identical to the scope requested by the client; otherwise, **REQUIRED**.  The scope of the access token as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
          type: string
          example: 'read write'
    TokenError:
      title: TokenError
      description: |-
        [The OAuth2.0 Authorization Framework - 5.2. Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)
      type: object
      required:
        - error
      properties:
        error:
          description: |-
            A single ASCII [[USASCII](https://tools.ietf.org/html/rfc6749#ref-USASCII)] error code from the following:
            | Error Code| Description |
            |-----------|-------------|
            | invalid_request | The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. |
            | invalid_client | Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).  The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported.  If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. |
            | invalid_grant | The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
            | unauthorized_client | The authenticated client is not authorized to use this authorization grant type. |
            | unsupported_grant_type | The authorization grant type is not supported by the authorization server. |
            | invalid_scope | The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner. |
          type: string
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - invalid_scope
          example: invalid_client
        error_description:
          description: |-
            Human-readable ASCII [[USASCII](https://tools.ietf.org/html/rfc6749#ref-USASCII)] text providing additional information, used to assist the client developer in understanding the error that occurred.
          type: string
          example: Client authentication failed
        error_uri:
          description: |-
            A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
          type: string
          example: 'http://example.test/client_authentication_failed.html'
  responses:
    OAuth2TokenSuccessResponse:
      description: |-
        Successful Response.

        [The OAuth2.0 Authorization Framework - 5.1. Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1)

        The authorization server issues an access token and optional refresh token, and constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code.
      headers:
        Cache-Control:
          schema:
            type: string
            example: no-store
        Pragma:
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Token'
    OAuth2TokenErrorResponse:
      description: |-
        Error Response.

        [The OAuth2.0 Authorization Framework - 5.2. Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)

        The authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response.

        Values for the "error" parameter **MUST NOT** include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
      headers:
        Cache-Control:
          schema:
            type: string
            example: no-store
        Pragma:
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenError'
  requestBodies:
    TokenRequestCodeGrant:
      description: |-
        Access token request body
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
              - grant_type
              - code
            properties:
              grant_type:
                description: |-
                  Value **MUST** be set to "authorization_code".
                type: string
                enum:
                  - authorization_code
                example: authorization_code
              code:
                description: |-
                  The authorization code received from the authorization server.
                type: string
                example: SplxlOBeZQQYbYS6WxSbIA
              redirect_uri:
                description: |-
                  **REQUIRED**, if the "redirect_uri" parameter was included in the authorization request as described in Section [4.1.1](https://tools.ietf.org/html/rfc6749#section-4.1.1), and their values **MUST** be identical.
                type: string
                example: 'https://client.example.com/cb'
              client_id:
                description: |-
                  **REQUIRED**, if the client is not authenticating with the authorization server as described in Section [3.2.1](https://tools.ietf.org/html/rfc6749#section-3.2.1).
                type: string
                example: s6BhdRkqt3
      required: true
    TokenRequestPasswordGrant:
      description: |-
        Access token request body
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
              - grant_type
              - username
              - password
            properties:
              grant_type:
                description: |-
                  Value **MUST** be set to "password".
                type: string
                enum:
                  - password
                example: password
              username:
                description: |-
                  The resource owner username.
                type: string
                example: johndoe
              password:
                description: |-
                  The resource owner password.
                type: string
                example: A3ddj3w
              scope:
                description: |-
                  The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
                type: string
                example: read write
      required: true
    TokenRequestClientCredentialsGrant:
      description: |-
        Access token request body
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
              - grant_type
            properties:
              grant_type:
                description: |-
                  Value **MUST** be set to "client_credentials".
                type: string
                enum:
                  - client_credentials
                example: client_credentials
              scope:
                description: |-
                  The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
                type: string
                example: read write
      required: true
    TokenRequestRefreshGrant:
      description: |-
        Access token request body
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
              - grant_type
              - refresh_token
            properties:
              grant_type:
                description: |-
                  Value **MUST** be set to "refresh_token".
                type: string
                enum:
                  - refresh_token
                example: refresh_token
              refresh_token:
                description: |-
                  The refresh token issued to the client.
                type: string
                example: tGzv3JOkF0XG5Qx2TlKWIA
              scope:
                description: |-
                  The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).  The requested scope **MUST NOT** include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.
                type: string
                example: read write
      required: true
  securitySchemes:
    ClientPasswordHttpBasic:
      description: |-
        Clients in possession of a client password MAY use the HTTP Basic authentication scheme as defined in [[RFC2617](https://tools.ietf.org/html/rfc2617)] to authenticate with the authorization server.

        Use "client_id" as username and "client_secret" as password.

        [RFC 6749 - 2.3.1. Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1)
      type: http
      scheme: Basic