openapi: 3.1.0
info:
  title: OAuth API
  description: OAuth 2.0 client credentials token endpoint and token lifecycle.
  version: v1
paths:
  /v1beta1/users/oauth2/token:
    post:
      summary: |-
        Exchange client credentials for an access token.
         Standard OAuth 2.0 client credentials grant (RFC 6749 §4.4).
      description: |-
        Errors:
           - invalid_client: client_id/client_secret invalid or client inactive.
           - invalid_request: missing or malformed parameter.
           - invalid_scope: scope is not `openid`.
           - unauthorized_client: client not allowed client_credentials grant.
           - unsupported_grant_type: grant_type is not client_credentials.
      operationId: Token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        "400":
          description: Missing or malformed parameter, or unsupported grant type.
        "401":
          description: Invalid client credentials.
  /v1beta1/users/oauth2/revoke:
    post:
      summary: |-
        Revoke an access token.
         Conforms to RFC 7009.
      description: |-
        Errors:
           - invalid_client: client_id/client_secret invalid.
      operationId: RevokeToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
        required: true
      responses:
        "200":
          description: Token revoked (or was already invalid).
        "401":
          description: Invalid client credentials.
      security:
        - BasicAuth: []
components:
  schemas:
    TokenRequest:
      type: object
      properties:
        grant_type:
          type: string
          title: grant_type
          enum:
            - client_credentials
          description: Must be `client_credentials`.
        client_id:
          type: string
          title: client_id
          description: The OAuth 2.0 client ID (UUID) returned from client creation.
        client_secret:
          type: string
          title: client_secret
          description: The OAuth 2.0 client secret returned from client creation.
        scope:
          type: string
          title: scope
          description: (OPTIONAL) Only `openid` is supported. Defaults to the client's configured scope if omitted.
      title: TokenRequest
      required:
        - grant_type
        - client_id
        - client_secret
      additionalProperties: false
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          title: access_token
          description: The opaque access token.
        token_type:
          type: string
          title: token_type
          description: Always `Bearer`.
        expires_in:
          type: integer
          title: expires_in
          description: Token lifetime in seconds.
        scope:
          type: string
          title: scope
          description: Granted scopes.
      title: TokenResponse
      additionalProperties: false
    RevokeRequest:
      type: object
      properties:
        token:
          type: string
          title: token
          minLength: 1
          description: The access token to revoke.
      title: RevokeRequest
      required:
        - token
      additionalProperties: false
  securitySchemes:
    BasicAuth:
      type: http
      description: client_id:client_secret as HTTP Basic credentials.
      scheme: basic
security: []
