Portal Login: /portal/login
Purpose
This API allows users to authenticate into the portal by providing valid login credentials. It validates the user’s email and password combination and returns user details along with portal access permissions. The response includes metadata such as account type, user name, email address, portal access flag, and the list of associated portals.
Use Case
- Enable users to log into the system using their email and password.
- Retrieve user details immediately after login for personalized experiences.
- Provide information on which portals the user has access to, ensuring proper role-based redirection.
- Support multi-portal environments where one user may belong to multiple accounts.
Path Parameters
This endpoint does not require path parameters.
Query Parameters
This endpoint does not support query parameters.
Request Body
{
"email": "{{USER_EMAIL}}",
"password": "{{USER_PASSWORD}}"
}
| Attribute | Type | Description |
|---|---|---|
email |
string | Registered email address of the user. |
password |
string | Corresponding password for the email. |
Response
On successful authentication, the response returns a user object containing essential account details. This includes the account type (ACCOUNT or other role-based types), display name, registered email address, and the grant_access_portal flag, which indicates whether the user is permitted to access the portal. Additionally, the response contains an array of portals representing all the portals available to the user. Each portal includes its unique identifier (uuid), associated account ID, and a display name. This ensures that multi-account users can easily switch between portals they have access to.
Response Body
{
"user": {
"type": "{{USER_TYPE}}",
"name": "{{USER_NAME}}",
"email_address": "{{USER_EMAIL}}",
"image_uri": "{{PROFILE_IMAGE_URI}}",
"grant_access_portal": "{{BOOLEAN_STRING}}",
"portals": [
{
"account": "{{ACCOUNT_ID}}",
"display_name": "{{PORTAL_DISPLAY_NAME}}",
"uuid": "{{PORTAL_UUID}}"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
user |
object | Contains details about the authenticated user. |
user.type |
string | Type of the user. |
user.name |
string | Display name of the user. |
user.email_address |
string | Email address used for login. |
user.image_uri |
string (URL) | URI of the user’s profile image, if available. Empty if not set. |
user.grant_access_portal |
string (boolean) | Indicates if the user is allowed to access the portal (true/false as string). |
user.portals |
array of objects | List of portals accessible by the user. |
user.portals.account |
string | Unique identifier of the associated account. |
user.portals.display_name |
string | Display name for the portal. |
user.portals.uuid |
string (UUID) | Unique identifier of the portal. |
Change Portal Password: /portal/change-password
Purpose
This API allows an authenticated user to change their portal password securely. By validating the provided current password against the stored credentials, the system ensures that only legitimate users can update their password. On success, the API updates the user’s password to the new value and returns a confirmation message.
Use Case
- Allow users to update their password when they remember the current one but want to strengthen security.
- Enforce password rotation policies by prompting users to change their password.
- Provide a self-service option for users to manage their credentials without admin intervention.
- Prevent unauthorized password changes by requiring the current password for verification.
Path Parameters
This endpoint does not require path parameters.
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"email": "{{USER_EMAIL}}",
"current_password": "{{CURRENT_PASSWORD}}",
"new_password": "{{NEW_PASSWORD}}"
}
| Attribute | Type | Description |
|---|---|---|
email |
string | Registered email address of the user whose password is being changed. |
current_password |
string | The existing password used for authentication. |
new_password |
string | The new password the user wants to set. Must follow system’s password policy. |
Response
On a successful request, the API responds with a simple confirmation message indicating that the password has been changed. This ensures users receive immediate feedback confirming the success of the operation. If the current password is incorrect, or the new password violates password policies, the API will typically return an error (not shown here but recommended to be handled in implementation).
Response Body
{
"message": "Password changed successfully"
}
| Attribute | Type | Description |
|---|---|---|
message |
string | Success message confirming that the password was updated. |