API Docs - RelatedTitle/user-account-system GitHub Wiki

API Docs

For authenticated endpoints, the access token should be sent in a header called "secret_token".

Example:

{
"secret_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4"
}

For CAPTCHA:

You can choose to use hCaptcha or reCAPTCHA, or neither, or both, as long as you enable/disable them in config.

TIP: You can use 10000000-aaaa-bbbb-cccc-000000000001 as the h-captcha-response token for testing if you are using the testing secret in config.

TIP: You can use anything as the g-captcha-response token for testing if you are using the testing secret in config.

Endpoints:

`POST /auth/register`

This endpoint is used for registering new users.

Body:

email: The user's email, must be unique and match the email regex set in config. (Required)

username: The user's username, must be unique and match the username regex set in config. (Required)

password: The user's password, must follow the password regex set in config. (Required)

h-captcha-response: The hCaptcha response token from the widget. (Required if hCaptcha is enabled)

g-captcha-response: The reCAPTCHA response token from the widget. (Required if reCAPTCHA is enabled)

Example request:

curl -d "[email protected]&username=johndoe&password=123123123@Aa&h-captcha-response=10000000-aaaa-bbbb-cccc-000000000001" -X POST http://localhost/auth/register

Example response:

{
    "error": false, // Whether there was an error or not.
    "message": "User registered successfully",
    "user": {
        "userid": 5901057193,
        "username": "johndoe",
        "email": "[email protected]"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4",
// Access token, used for authenticated endpoints.
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNjI2MDY5MTI1fQ.T2UYeumro0vjZorNm9VnQXs6Ckzpcm9Dic7oWTm6Qb0"
// Refresh token, used for refreshing the access token (using the /auth/refresh_token endpoint).
}

`POST /auth/login`

This endpoint is used for logging in existing users.

Body:

email: The user's email. (Required)

password: The user's password. (Required)

totp_code: The user's TOTP code for 2FA (Only required if the user has 2FA enabled)

h-captcha-response: The hCaptcha response token from the widget. (Required if hCaptcha is enabled)

g-captcha-response: The reCAPTCHA response token from the widget. (Required if reCAPTCHA is enabled)

Example request:

curl -d "[email protected]&password=123123123@Aa" -X POST http://localhost/auth/login

Example response:

{
    "error": false, // Whether there was an error or not.
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4",
// Access token, used for authenticated endpoints.
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNjI2MDY5MTI1fQ.T2UYeumro0vjZorNm9VnQXs6Ckzpcm9Dic7oWTm6Qb0"
// Refresh token, used for refreshing the access token (using the /auth/refresh_token endpoint).
}

`POST /auth/refresh_token`

This endpoint is used for issuing a new access token using the refresh token.

Body:

refresh_token: The user's active refresh token. (Required)

Example request:

curl -d "refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNjI2MDc4MTQ3fQ.LuHdkFUM5N6ldZfid5R4Qo2tZUVCt6Lte_trjpluDnI" -X POST http://localhost/auth/refresh_token

Example response:

{
    "error": false, // Whether there was an error or not.
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNzgxODh9.NS772UinKM_zShARHpAKGXGgl1B7wBiY09HHIVPEMYA"
    // Access token, used for authenticated endpoints.
}

`POST /auth/request_password_reset`

This endpoint is used for requesting password resets. If a user with the provided email exists, a password reset email will be sent. The user can then reset their password by following the link in the email.

Body:

email: The user's email. (Required)

h-captcha-response: The hCaptcha response token from the widget. (Required if hCaptcha is enabled)

g-captcha-response: The reCAPTCHA response token from the widget. (Required if reCAPTCHA is enabled)

Example request:

curl -d "[email protected]" -X POST http://localhost/auth/request_password_reset

Example response:

{
    "error": false, // Whether there was an error or not.
    "message": "Password reset email sent"
}

`POST /auth/reset_password`

This endpoint is used for resetting a user's password (after requesting a password reset). This endpoint requires a password reset token which should be included as a parameter/query in a link to the frontend in the password reset email. The frontend should then send this request with the token and the new password the user chose. All of the user's active refresh tokens will be expired after successfully resetting the password.

Ex. http://localhost/frontend/reset_password?eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJ0eXBlIjoicGFzc3dvcmRyZXNldCIsImlhdCI6MTYyNjA3ODUyN30.7eQbRTdb9NGyD_wHkbqW9WyUPR7XKeSEMzhz4hDm08o

Body:

password_reset_token: The password reset token included as a parameter in a link to the frontend in the password reset email. (Required)

password: The user's new password, must follow the password regex set in config and be different from the current one. (Required)

Example request:

curl -d "password_reset_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJ0eXBlIjoicGFzc3dvcmRyZXNldCIsImlhdCI6MTYyNjA3ODUyN30.7eQbRTdb9NGyD_wHkbqW9WyUPR7XKeSEMzhz4hDm08o&password=321321321@Aa" -X POST http://localhost/auth/reset_password

Example response:

{
    "error": false, // Whether there was an error or not.
    "message": "Password changed successfully"
}

`POST /auth/verify_email`

This endpoint is used for verifying a user's email (after changing it or sign up). This endpoint requires an email verification token which should be included as a parameter/query in a link to the frontend in the verification email. The frontend should then send this request with the token.

Ex. http://localhost/frontend/verify_email?eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyaWQiOjc3NDkyMDI5MTUsImVtYWlsIjoiam9objFAZXhhbXBsZS5jb20iLCJ0eXBlIjoiZW1haWx2ZXJpZmljYXRpb24iLCJpYXQiOjE2MjYwNzUyNTJ9.91OenVYqNUMDCFvNtmklKZH6ViqkRDLwQXJmMjp5pwI

Body:

email_verification_token: The email verification token included as a parameter in a link to the frontend in the verification email. (Required)

Example request:

curl -d "email_verification_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyaWQiOjc3NDkyMDI5MTUsImVtYWlsIjoiam9objFAZXhhbXBsZS5jb20iLCJ0eXBlIjoiZW1haWx2ZXJpZmljYXRpb24iLCJpYXQiOjE2MjYwNzUyNTJ9.91OenVYqNUMDCFvNtmklKZH6ViqkRDLwQXJmMjp5pwI" -X POST http://localhost/auth/verify_email

Example response:


{
"error": false, // Whether there was an error or not.
"message": "Email verified successfully"
}

`POST /auth/authorize_new_IP`

This endpoint is used for authorizing a new IP address to be able to log in to the user's account (after attempting to log in with it once). This endpoint requires a new IP token which should be included as a parameter/query in a link to the frontend in the new IP address authorization email. The frontend should then send this request with the token.

Ex. http://localhost/frontend/authorize_new_IP?eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyaWQiOjU5MDEwNTcxOTMsImlwIjoiOjoxIiwidHlwZSI6Im5ld0lQIiwiaWF0IjoxNjI2MjM4NTM4fQ.RTcwMqyJ6kUnmMW1fy-6YNfafPMFxSZdxjJ1uSLbnho

Body:

new_IP_token: The new IP token included as a parameter in a link to the frontend in the new IP address authorization email. (Required)

Example request:

curl -d "new_IP_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyaWQiOjU5MDEwNTcxOTMsImlwIjoiOjoxIiwidHlwZSI6Im5ld0lQIiwiaWF0IjoxNjI2MjM4NTM4fQ.RTcwMqyJ6kUnmMW1fy-6YNfafPMFxSZdxjJ1uSLbnho" -X POST http://localhost/auth/authorize_new_IP

Example response:

{
    "error": false, // Whether there was an error or not.
    "message": "New IP address authorized successfully"
}

`POST /user/change_password`

This endpoint is used for changing a user's password. All of the user's active refresh tokens (except the one used for this request) will be expired upon successfully changing the password.

Headers:

secret_token: The user's active access token.

Body:

old_password: The user's old password. (Required)

new_password: The user's new password (The one to be changed to), must follow the password regex set in config and be different from the current one. (Required)

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -d "old_password=123123123@Aa&new_password=321321321@Aa" -X POST http://localhost/user/change_password

Example response:


{
"error": false, // Whether there was an error or not.
"message": "Password changed successfully"
}

`POST /user/change_email`

This endpoint is used for changing a user's email. The user has to verify the new email (by following the link sent) in order for it to become the active email.

Headers:

secret_token: The user's active access token.

Body:

email: The user's new email (The one to be changed to), must follow the email regex set in config and be different from the current one. (Required)

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -d "[email protected]" -X POST http://localhost/user/change_email

Example response:


{
"error": false, // Whether there was an error or not.
"message": "Email verification sent successfully"
}

`POST /user/request_2FA_secret`

This endpoint is used for requesting a 2FA secret. The secret will be added to the user's account but will not be active until the user proves that they can generate codes with it by the /user/activate_2FA endpoint. The user must NOT have 2FA already enabled.

Headers:

secret_token: The user's active access token.

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -X POST http://localhost/user/request_2FA_secret

Example response:


{
"error": false, // Whether there was an error or not.
"totp_secret": "DM4DQQ3EMVDQYASE" // The TOTP secret to generate codes from.
}

`POST /user/activate_2FA`

This endpoint is used for activating 2FA. The user must provide a TOTP code generated using the secret previously obtained through the /user/request2FAsecret endpoint. If the TOTP code is correct, 2FA will be enabled.

Headers:

secret_token: The user's active access token.

Body:

totp_code: The TOTP code generated from the secret.

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -d "totp_code=123123" -X POST http://localhost/user/activate_2FA

Example response:


{
"error": false, // Whether there was an error or not.
"message": "2FA activated successfully"
}

`POST /user/disable_2FA`

This endpoint is used for disabling 2FA. The user must provide a TOTP code generated using the secret of the 2FA they want to disable. If the TOTP code is correct, 2FA will be disabled.

Headers:

secret_token: The user's active access token.

Body:

totp_code: The TOTP code generated from the secret.

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -d "totp_code=123123" -X POST http://localhost/user/disable_2FA

Example response:


{
"error": false, // Whether there was an error or not.
"message": "2FA disabled successfully"
}

`POST /user/change_avatar`

This endpoint is used for changing the user's avatar. It is of type multipart/form-data and accepts 1 image file.

Headers:

secret_token: The user's active access token.

Body:

avatar: The avatar image.

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -F [email protected] -X POST http://localhost/user/change_avatar

Example response:


{
"error": false, // Whether there was an error or not.
"message": "Avatar uploaded successfully."
}

`POST user/expire_token`

This endpoint is used for expiring a user's refresh tokens. It can expire all tokens, all tokens except the one used to make the request, or only specific tokens. If you want to expire all the refresh tokens, set expire_all in the request body to true. If you want to expire all the tokens except the one made for the request, set expire_all and exclude_current to true. If you only want to expire specific tokens, provide an array called tokens with the tokens you wish to expire.

Headers:

secret_token: The user's active access token.

Body:

expire_all: Whether all of the user's active refresh tokens should be expired.

exclude_current: Whether the token used to make the request should be excluded (when using expire_all).

tokens: The specific tokens to expire.

Example request:


curl -H "secret_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6NTkwMTA1NzE5MywiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0sInR5cGUiOiJhY2Nlc3MiLCJpYXQiOjE2MjYwNjkxMjV9.eIFU1TpYZ5DCTeoV5hizd-8ExvMs_mo4DAQfAOpQhm4" -d "expire_all=true&exclude_current=false" -X POST http://localhost/user/expire_token

Example response:


{
"error": false, // Whether there was an error or not.
"message": "Tokens expired successfully."
}