swagger: "2.0"
info:
  title: allaboutapps.dev/aw/go-starter
  version: 0.1.0
responses:
  InvalidPasswordResponse:
    description: "PublicHTTPValidationError, type `INVALID_PASSWORD`"
    schema:
      $ref: ../definitions/errors.yml#/definitions/PublicHTTPValidationError
  AuthUnauthorizedResponse:
    description: PublicHTTPError
    schema:
      $ref: ../definitions/errors.yml#/definitions/PublicHTTPError
  AuthForbiddenResponse:
    description: "PublicHTTPError, type `USER_DEACTIVATED`/`NOT_LOCAL_USER`"
    schema:
      $ref: ../definitions/errors.yml#/definitions/PublicHTTPError
  ValidationError:
    description: PublicHTTPValidationError
    schema:
      $ref: "../definitions/errors.yml#/definitions/PublicHTTPValidationError"
parameters:
  registrationTokenParam:
    type: string
    format: uuid4
    in: path
    name: registrationToken
    description: Registration token to complete the registration process
    required: true
paths:
  /api/v1/auth/change-password:
    post:
      security:
        - Bearer: []
      description: |-
        After successful password change, all current access and refresh tokens are
        invalidated and a new set of auth tokens is returned
      tags:
        - auth
      summary: Change local user's password
      operationId: PostChangePasswordRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: ../definitions/auth.yml#/definitions/PostChangePasswordPayload
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: ../definitions/auth.yml#/definitions/PostLoginResponse
        "400":
          $ref: "#/responses/InvalidPasswordResponse"
        "401":
          $ref: "#/responses/AuthUnauthorizedResponse"
        "403":
          $ref: "#/responses/AuthForbiddenResponse"

  /api/v1/auth/forgot-password:
    post:
      description: |-
        Initiates a password reset for a local user, sending an email with a password
        reset link to the provided email address if a user account exists. Will always
        succeed, even if no user was found in order to prevent user enumeration
      tags:
        - auth
      summary: Initiate password reset for local user
      operationId: PostForgotPasswordRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostForgotPasswordPayload"
      responses:
        "204":
          description: Success
        "400":
          $ref: "#/responses/ValidationError"
  /api/v1/auth/forgot-password/complete:
    post:
      description: |-
        Completes a password reset for a local user, using the password reset token sent via email
        to confirm user access, setting the new password if successful. All current access and refresh
        tokens are invalidated and a new set of auth tokens is returned
      tags:
        - auth
      summary: Completes password reset for local user
      operationId: PostForgotPasswordCompleteRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostForgotPasswordCompletePayload"
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginResponse"
        "400":
          $ref: "#/responses/InvalidPasswordResponse"
        "403":
          $ref: "#/responses/AuthForbiddenResponse"
        "404":
          description: "PublicHTTPError, type `TOKEN_NOT_FOUND`"
          schema:
            $ref: "../definitions/errors.yml#/definitions/PublicHTTPError"
        "409":
          description: "PublicHTTPError, type `TOKEN_EXPIRED`"
          schema:
            $ref: "../definitions/errors.yml#/definitions/PublicHTTPError"
  /api/v1/auth/login:
    post:
      description: Returns an access and refresh token on successful authentication
      tags:
        - auth
      summary: Login with local user
      operationId: PostLoginRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginPayload"
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginResponse"
        "400":
          $ref: "#/responses/ValidationError"
        "401":
          $ref: "#/responses/AuthUnauthorizedResponse"
        "403":
          description: "PublicHTTPError, type `USER_DEACTIVATED`"
          schema:
            $ref: "../definitions/errors.yml#/definitions/PublicHTTPError"
  /api/v1/auth/logout:
    post:
      security:
        - Bearer: []
      description: |-
        Logs the local user out, destroying the provided access token.
        A refresh token can optionally be provided, destroying it as well if found.
      tags:
        - auth
      summary: Log out local user
      operationId: PostLogoutRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLogoutPayload"
      responses:
        "204":
          description: Success
        "400":
          $ref: "#/responses/ValidationError"
        "401":
          $ref: "#/responses/AuthUnauthorizedResponse"
  /api/v1/auth/refresh:
    post:
      description: |-
        Returns a fresh set of access and refresh tokens if a valid refresh token was provided.
        The old refresh token used to authenticate the request will be invalidated.
      tags:
        - auth
      summary: Refresh tokens
      operationId: PostRefreshRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostRefreshPayload"
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginResponse"
        "400":
          $ref: "#/responses/ValidationError"
        "401":
          $ref: "#/responses/AuthUnauthorizedResponse"
        "403":
          description: "PublicHTTPError, type `USER_DEACTIVATED`"
          schema:
            $ref: "../definitions/errors.yml#/definitions/PublicHTTPError"
  /api/v1/auth/register:
    post:
      description: |
        Registers a local user. If the registration process requires a confirmation
        the status code `202` is returned without auth tokens. Afterwards the registration needs to be confirmed
        using the `POST /api/v1/auth/register/{registrationToken}` endpoint.
      tags:
        - auth
      summary: Registers a local user
      operationId: PostRegisterRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostRegisterPayload"
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginResponse"
        "202":
          description: RegisterResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/RegisterResponse"
        "400":
          $ref: "#/responses/InvalidPasswordResponse"
        "409":
          description: "PublicHTTPError, type `USER_ALREADY_EXISTS`"
          schema:
            $ref: "../definitions/errors.yml#/definitions/PublicHTTPError"
    get:
      summary: Page to complete registration
      tags:
        - auth
      operationId: GetCompleteRegisterRoute
      parameters:
        - name: token
          in: query
          type: string
          format: uuid4
          description: Registration token to complete the registration process
          required: true
      produces:
        - text/html
      responses:
        "200":
          description: Page to complete registration
  /api/v1/auth/register/{registrationToken}:
    post:
      summary: Complete registration
      description: |-
        Completes registration for a local user
      tags:
        - auth
      operationId: PostCompleteRegisterRoute
      parameters:
        - $ref: "#/parameters/registrationTokenParam"
      responses:
        "200":
          description: PostLoginResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/PostLoginResponse"
        "401":
          description: Unauthorized
  /api/v1/auth/userinfo:
    get:
      summary: Get user info
      description: |-
        Returns user information compatible with the OpenID Connect Core 1.0 specification.
        Information returned depends on the requesting user as some data is only available if an app user profile exists.
      security:
        - Bearer: []
      operationId: GetUserInfoRoute
      tags:
        - auth
      responses:
        "200":
          description: GetUserInfoResponse
          schema:
            $ref: "../definitions/auth.yml#/definitions/GetUserInfoResponse"
  /api/v1/auth/account:
    delete:
      summary: Delete user account
      description: |-
        Completely delete the user account. This action is irreversible and therefore requires additional password authentication.
      security:
        - Bearer: []
      operationId: DeleteUserAccountRoute
      parameters:
        - name: Payload
          in: body
          schema:
            $ref: ../definitions/auth.yml#/definitions/DeleteUserAccountPayload
      tags:
        - auth
      responses:
        "204":
          description: NoContent
        "400":
          $ref: "#/responses/InvalidPasswordResponse"
        "401":
          $ref: "#/responses/AuthUnauthorizedResponse"
        "403":
          $ref: "#/responses/AuthForbiddenResponse"