Module user

API context: user.

This API context is responsible for handling:

• User registration
• User authentication
• User ban

For more information about the API authentication, refer to the auth module.

Endpoints

Registration:

• Registration
• Email verification

Authentication:

• Login
• Token verification
• Token renewal

User ban:

• Ban a user

Registration

POST /v1/user/register

It registers a new user.

Post parameters

Name	Type	Description	Required	Example
username	String	The username	Yes	indexadmin
email	Option<String>	The user’s email	No	indexadmin@torrust.com
password	String	The password	Yes	BenoitMandelbrot1924
confirm_password	String	Same password again	Yes	BenoitMandelbrot1924

NOTICE: Email could be optional, depending on the configuration.

[auth]
email_on_signup = "Optional"
min_password_length = 6
max_password_length = 64

Refer to the RegistrationForm struct for more information about the registration form.

Example request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"username":"indexadmin","email":"indexadmin@torrust.com","password":"BenoitMandelbrot1924","confirm_password":"BenoitMandelbrot1924"}' \
  http://127.0.0.1:3001/v1/user/register

For more information about the registration process, refer to the auth module.

Email verification

GET /v1/user/email/verify/{token}

If email on signup is enabled, the user will receive an email with a verification link. The link will contain a token that can be used to verify the email address.

This endpoint will verify the email address and update the user’s email verification status. It also shows an text page with the result of the verification.

Example response 200

Email verified, you can close this page.

Login

POST /v1/user/login

It logs in a user.

Post parameters

Name	Type	Description	Required	Example
login	String	The password	Yes	indexadmin
password	String	The password	Yes	BenoitMandelbrot1924

Refer to the LoginForm struct for more information about the login form.

Example request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"login":"indexadmin","password":"BenoitMandelbrot1924"}' \
  http://127.0.0.1:3001/v1/user/login

For more information about the login process, refer to the auth module.

Token verification

POST /v1/user/token/verify

It logs in a user.

Post parameters

Name	Type	Description	Required	Example
token	String	The token you want to verify	Yes	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI

Refer to the JsonWebToken struct for more information about the token.

Example request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI"}' \
  http://127.0.0.1:3001/v1/user/token/verify

Example response 200

For a valid token:

{
  "data":"Token is valid."
}

And for an invalid token:

{
  "data":"Token invalid."
}

Token renewal

POST /v1/user/token/verify

It renew a user’s token.

The token must be valid and not expired. And it’s only renewed if it is valid for less than one week.

Post parameters

Name	Type	Description	Required	Example
token	String	The current valid token	Yes	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI

Refer to the JsonWebToken struct for more information about the token.

Example request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI"}' \
  http://127.0.0.1:3001/v1/user/token/renew

Example response 200

If you try to renew a token that is still valid for more than one week:

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI",
    "username": "indexadmin",
    "admin": true
  }
}

You will get the same token. If a new token is generated, the response will be the same but with the new token.

WARNING: The token is associated to the user’s role. The application does not support changing the role of a user. If you change the user’s role manually in the database, the token will still be valid but with the same role. That should only be done for testing purposes.

Ban a user

DELETE /v1/user/ban/{user}

It add a user to the banned user list.

Only admin can ban other users.

Path parameters

Name	Type	Description	Required	Example
user	String	username	Yes	indexadmin

Example request

curl \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI" \
  --request DELETE \
  http://127.0.0.1:3001/v1/user/ban/indexadmin

Example response 200

If you try to renew a token that is still valid for more than one week:

{
  "data": "Banned user: indexadmin"
}

WARNING: The admin can ban themselves. If they do, they will not be able to unban themselves. The only way to unban themselves is to manually remove the user from the banned user list in the database.

Modules

forms

handlers

API handlers for the the user API context.

responses

routes

API routes for the user API context.