289 lines
9.6 KiB
YAML
289 lines
9.6 KiB
YAML
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" |