🌐 API
Auth Server is a general-purpose HTTP-based authentication and authorization server.
The authentication method used to make requests is
JSON Web Token
. After a successful sign up and email verification users can request authorization to resources
using their credentials. Then the server responds with an access token.
{
sub: username
}
The client must send the token in the
authorization header
when making protected requests.
Authorization: Bearer <token>
Responses and errors are encapsulated in a JSON object that adds metadata to the message.
{
version: <version>
endpoint: <endpoint>
timestamp: <timestamp>
<data|error>
}
/signup
Sign up to the server.
Request
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| password |
string |
The user's password (Base64). |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
/signdown
Sign down from the server.
Request
user / admin
| Field |
Type |
Description |
| password |
string |
The user's password (Base64). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/signin
Sign in authenticating with email and password.
Request
| Field |
Type |
Description |
| email |
string |
The user's email. |
| password |
string |
The user's password (Base64). |
Response
| Field |
Type |
Description |
| token |
string |
The token used to make protected requests. |
/verify-email/:token
Verify the user's email.
Request
This request doesn't have a body.
Response
| Field |
Type |
Description |
| verified |
boolean |
The email was verified. |
/change-email/:token
Change the user's email.
Request
This request doesn't have a body.
Response
| Field |
Type |
Description |
| changed |
boolean |
The email was changed. |
/forgot-password
Request the server an email to change the password.
Request
| Field |
Type |
Description |
| email |
string |
The user's email. |
Response
| Field |
Type |
Description |
| sent |
boolean |
The verification email was sent. |
/change-password/:token
Change the user's password.
Request
| Field |
Type |
Description |
| password |
string |
The new user's password (Base64). |
Response
| Field |
Type |
Description |
| changed |
boolean |
The password was changed. |
/users/me
Get my user's data.
Request
user / admin
This request doesn't have a body.
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username
Get the user's data.
Request
admin
This request doesn't have a body.
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/
Get all the users' data.
Request
admin
This request doesn't have a body.
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/avatar
Get my user's avatar.
Request
user / admin
This request doesn't have a body.
Response
| Field |
Type |
Description |
| avatar |
string |
The user's avatar URL. |
/users/:username/avatar
Get the user's avatar.
Request
user / admin
This request doesn't have a body.
Response
| Field |
Type |
Description |
| avatar |
string |
The user's avatar URL. |
/users/me/username
Change my user's username.
Request
user / admin
| Field |
Type |
Description |
| username |
string |
The new user's username. |
| password |
string |
The user's password (Base64). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username/username
Change the user's username.
Request
admin
| Field |
Type |
Description |
| username |
string |
The new user's username. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/email
Change my user's email.
Request
user / admin
| Field |
Type |
Description |
| email |
string |
The new user's email. |
Response
| Field |
Type |
Description |
| sent |
boolean |
The verification email was sent. |
/users/me/password
Change my user's password.
Request
user / admin
| Field |
Type |
Description |
| currentPassword |
string |
The user's password (Base64). |
| newPassword |
string |
The new user's password (Base64). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/avatar
Change my user's avatar.
Request
user / admin
| Field |
Type |
Description |
| avatar |
string |
The new user's avatar URL. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username/avatar
Change the user's avatar.
Request
admin
| Field |
Type |
Description |
| avatar |
string |
The new user's avatar URL. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/name
Change my user's name.
Request
user / admin
| Field |
Type |
Description |
| name |
string |
The new user's name. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username/name
Change the user's name.
Request
admin
| Field |
Type |
Description |
| name |
string |
The new user's name. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/surname
Change my user's surname.
Request
user / admin
| Field |
Type |
Description |
| surname |
string |
The new user's surname. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username/surname
Change the user's surname.
Request
admin
| Field |
Type |
Description |
| surname |
string |
The new user's surname. |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/me/birthdate
Change my user's birthdate.
Request
user / admin
| Field |
Type |
Description |
| birthdate |
string |
The new user's birthdate (yyyy-MM-dd). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username/birthdate
Change the user's birthdate.
Request
admin
| Field |
Type |
Description |
| birthdate |
string |
The new user's birthdate (yyyy-MM-dd). |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
/users/:username
Delete the user's data.
Request
admin
| Field |
Type |
Description |
| - |
- |
- |
Response
| Field |
Type |
Description |
| username |
string |
The user's username. |
| email |
string |
The user's email. |
| avatar |
string |
The user's avatar URL. |
| name |
string |
The user's name. |
| surname |
string |
The user's surname. |
| birthdate |
string |
The user's birthdate (yyyy-MM-dd). |
| roles |
string[] |
The user's roles. |
❌ Errors
The server uses the following error schema:
| Field |
Type |
| code |
string |
| message |
string |
| data |
object |
| Code |
Status |
Description |
| generic_error |
500 |
Generic error. |
| unknown_error |
500 |
Unknown error. |
| invalid_request |
400 |
Invalid request. |
| forbidden |
403 |
Forbidden. |
| validation_error |
400 |
Validation error. |
| username_taken |
409 |
Username is already being used. |
| email_taken |
409 |
Email is already being used. |
| email_not_verified |
401 |
Email not verified. |
| invalid_credentials |
401 |
Invalid credentials. |
| invalid_token |
401 |
Invalid token. |
| role_not_found |
404 |
Role not found. |
| user_not_found |
404 |
User not found. |
| mail_service_error |
503 |
Mail service error. |