Portal Post API Documentation

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

                JSON
              
                      {
  "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

                JSON
              

                      {
  "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.

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

                JSON
              

                      {
  "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

                JSON
              
                      {
  "message": "Password changed successfully"
}

Portal Login: /portal/login

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Change Portal Password: /portal/change-password

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body