User management and authentication

The login process typically involves the following steps:

The user is registered into the system by an administrative or by self-registration.
The user is activated by the administrative when required, after self-registration only.
The user provides their login details via system API, typically email and password.
The system validates the credentials and, if valid, issues an authentication JSON Web Token (JWT), tokens are used for access and refresh.
The user includes the JSON Web Token as a Bearer token in the Authorization header of subsequent API requests.
The system verifies the token on each request to ensure the user is authenticated and authorized to access the requested resources.
If the token is expired or invalid, the user must re-authenticate to obtain a new token.
Optionally, a refresh token mechanism may be used to allow users to obtain a new JWT without re-entering credentials.
- The refresh token is provided as the Bearer token in the Authorization header of a specific refresh endpoint.
The user can log out, which typically involves invalidating the current token on the server side.
- Invalidating the access token also invalidates the refresh token linked to the current session the access token manages.

Logs in a user with the provded email and password.

POST /api/v1/users/login

{
    "email": "account.login@example.com",
    "password": "#P4ssword"
}

Expected Response:

{
    "status": 200,
    "expiresIn": 3600,
    "type": "string",
    "message": "string",
    "tokenType": "bearer",
    "accessToken": "...",
    "refreshToken": "...",
    "data": [ ],
    "roles": [ { <Role> } ],
    "scopes": [ { <Scope> } ]
}

Description of the refresh token mechanism

The refresh token mechanism is designed to allow users to obtain a new access token without re-entering their credentials. This is particularly useful for long-lived sessions where the access token may expire.

How refresh tokens are issued, validated, and renewed?

Issuance: When a user logs in successfully, the system issues both an access token and a refresh token. The refresh token is typically stored securely on the client side (normally on session storage).

Validation: When a client presents a refresh token to obtain a new access token, the system validates the refresh token by checking its signature and expiration date.

Renewal: If the refresh token is valid, the system issues a new access token (and possibly a new refresh token) to the client.

Endpoint for interacting with refresh tokens

Refreshes the access token using the provided refresh token.

POST /api/v1/users/refresh
Authorization: Bearer <refresh_token>

Expected Response:

{
    "status": 200,
    "expiresIn": 3600,
    "type": "string",
    "message": "string",
    "tokenType": "bearer",
    "accessToken": "...",
    "refreshToken": "...",
    "data": [ ],
    "roles": [ { <Role> } ],
    "scopes": [ { <Scope> } ]
}

Description of the logout process

Logging out typically involves invalidating the refresh token on the server side, which also invalidates the associated access token and current session of the authenticated issuer.

Process for logging out users

The user initiates the logout process, typically by clicking a “Logout” button in the UI.
The client application sends a request to the server to log out the user.
The server invalidates the refresh token and associated access token.
The server responds to the client, confirming the logout.

Endpoints interacting with logout

Logs out the current user by invalidating the current access and refresh tokens.

POST /api/v1/users/logout
Authorization: Bearer <access_token>
Expect: 200-ok

Description of the password change process

Process for changing passwords

The client application sends a request to the server with the user’s current password and the new password.
The server validates the current password and, if valid, updates the user’s password to the new password.
The server responds to the client, confirming the password change.

Endpoint interacting with password change

Updates the password of the current user.

PUT /api/v1/users/change-password
Authorization: Bearer <access_token>

{
    "oldPassword": "#P4ssword",
    "newPassword": "#N3wP4ssword"
}

Expected Response:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "pagination": { <Pagination> },
    "data": [
        {
            "id": 1,
            "username": "account.password",
            "updatedAt": "2025-02-20T-21:05:29.648Z"
        }
    ]
}

Description of the user registration process

Data structures for users

Structure of Phone

The phone structure typically includes fields such as phone type and phone number.

Field	Type	Description
phoneTypeId	string	The type of phone
phoneNumber	string	The phone number

{
    "phoneTypeId": "2",
    "phoneNumber": "+1 (737) 888-1234"
}

Structure of Address

The address structure typically includes fields such as street, city, state, postal code, and country.

Field	Type	Description
street	string	The street address
city	string	The city address
state	string	The state or province
country	string	The country
postalcode	string	The postal code

{
    "street": "9442 N Capital of Texas Hwy",
    "city": "Austin",
    "state": "Texas",
    "country": "United States of America",
    "postalcode": "78759-0000"
}

Structure of User

The user structure typically includes fields which are belong to the user profile.

Field	Type	Description
active	boolean	Indicates if the user is active
department	integer	The department ID the user belongs to
doNotCall	boolean	Indicates if the user does not want to be called
title	string	The user’s title
salutation	string	The user’s salutation
description	string	A description of the user
firstName	string	The user’s first name
lastName	string	The user’s last name
password	string	The user’s password
username	string	The user’s username
email	string	The user’s email
phones	array	An array of phone objects
addresses	array	An array of address objects

{
    "active": true,
    "department": 1,
    "doNotCall": true,

    "title": "title",
    "salutation": "salutation",
    "description": "description",

    "email": "account.access@example.com",
    "username": "account.access",
    "password": "#P4ssword",
    "firstName": "Account",
    "lastName": "Access",

    "phones": [ { <Phone> } ],
    "addresses": [ { <Address> } ]
}

Endpoint interacting with administrative user creation

Creates a new user with the provided details by an administrative authenticated user.

POST /api/v1/users/
Authorization: Bearer <access_token>

<User>

Endpoint interacting with user self-registration

Creates a new user with the provided username, email and password.

POST /api/v1/users/register
Expect: 201-created

{
    "email": "account.register@example.com",
    "username": "account.register",
    "password": "#P4ssword",
    "firstName": "Account",
    "lastName": "Access"
}

Get all users

Get information about all users. Should get information about all active users.

Query Parameters

Name	Type	Description	Required	Example
limit	number	Records limit	No	`10`
page	number	Records page	No	`1`
firstName	string	First name	No	`John`
lastName	string	Last name	No	`Doe`
username	string	Username	No	`username`
email	string	Email	No	`account@example.com`
active	boolean	Active status	No	`true`

GET /api/v1/users/
Expect: 200-ok

Expected Response:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": [ { <User> } ],
    "pagination": { <Pagination> }
}

Get one user

Get information about a specific user.

Path Parameters

Name	Type	Description	Required	Example
id	string	User ID	Yes	`123`

GET /api/v1/users/:id
Expect: 200-ok

Expected Response:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}

Get current user

Get information about the current user.

GET /api/v1/users/me
GET /api/v1/users/profile
Authorization: Bearer <access_token>
Expect: 200-ok

Expected Response:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}

Update a user

Update information about a specific user.

Path Parameters

Name	Type	Description	Required	Example
id	string	User ID	Yes	`123`

PUT /api/v1/users/:id
Authorization: Bearer <access_token>
Expect: 200-ok

<User>

Expected Response:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}

User management and authentication

Description of the login process

Endpoint interacting with login

Description of the refresh token mechanism

How refresh tokens are issued, validated, and renewed?

Endpoint for interacting with refresh tokens

Description of the logout process

Process for logging out users

Endpoints interacting with logout

Description of the password change process

Process for changing passwords

Endpoint interacting with password change

Description of the user registration process

Data structures for users

Structure of Phone

Structure of Address

Structure of User

Endpoint interacting with administrative user creation

Endpoint interacting with user self-registration

Other actions related to user management

Get all users

Query Parameters

Get one user

Path Parameters

Get current user

Update a user

Path Parameters