Password

Password Authentication

This section covers the password-based authentication APIs available in SolidX.

Mental Model

Password authentication establishes a SolidX session from user credentials and then keeps that session active through access and refresh tokens.

Registration creates the user account when public registration is enabled.
Authentication exchanges credentials for tokens.
Refresh, password reset, user info, and logout manage the lifecycle of that session.

In a password-based flow, your application collects the user's email or username and password, then sends them to POST /api/iam/authenticate. If the credentials are valid, SolidX IAM returns two tokens:

accessToken: Send this with each protected API request in the Authorization: Bearer <ACCESS_TOKEN> header.
refreshToken: Use this only to request a new access token when the current one expires. Treat it as a long-lived secret. SolidX returns both tokens in the JSON response body. Store the refresh token as a sensitive credential, not as regular client-side application state.

When a protected REST API receives the bearer token, SolidX validates it, identifies the user, loads the user's roles, and makes that authenticated context available to the API request.

Password authentication sequence: register user, authenticate with password, call protected API with bearer token, and refresh tokens — The password flow starts with registration, exchanges credentials for tokens, and uses refresh tokens to continue the session.

The diagram above illustrates the standard password-authentication lifecycle. After a user account exists, the application submits the user's credentials to SolidX IAM. A successful authentication response returns an access token for protected API requests and a refresh token for renewing the session through the refresh endpoint.

Implementation Overview

SolidX provides a comprehensive password-based authentication mechanism with the following endpoints:

Register
Authenticate
Refresh Tokens
Forgot Password
Change Password
Get User Info
Logout

Token Lifecycle

The authenticate endpoint returns access and refresh tokens. Use the access token for protected API calls, and use the refresh token when the access token expires.

1. Register

Allows users to create a new account.

Endpoint

POST /api/iam/register

Environment Variables

IAM_ALLOW_PUBLIC_REGISTRATION: Allows public registration when set to true.

Headers

Content-Type: application/json

Request Body

{
  "fullName": "string",
  "username": "string",
  "email": "[EMAIL]",
  "password": "[PASSWORD]",
  "mobile": "string",
  "roles": ["string"]
}

Response Body

{
  "fullName": "string",
  "username": "string",
  "email": "[EMAIL]",
  "mobile": "string",
  "forcePasswordChange": true,
  "roles": [...],
  "id": 0,
  "createdAt": "...",
  "updatedAt": "..."
}

Response Note

The response body can be optimized. It currently includes sensitive data like passwords.

2. Authenticate

Endpoint

POST /api/iam/authenticate

Environment Variables

IAM_JWT_ACCESS_TOKEN_TTL: TTL for access tokens (default: 60 mins).
IAM_JWT_REFRESH_TOKEN_TTL: TTL for refresh tokens (default: 1 day).

Headers

Content-Type: application/json

Request Body

{
  "email": "[EMAIL]",
  "username": "",
  "password": "[PASSWORD]"
}

Response Body

{
  "data": {
    "user": {
      "email": "[EMAIL]",
      "username": "[EMAIL]",
      "roles": ["Admin", "Internal User"]
    },
    "accessToken": "<ACCESS_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>"
  }
}

3. Refresh Tokens

Refresh the access token using a valid refresh token.

Endpoint

POST /api/iam/refresh-tokens

Headers

Content-Type: application/json

Request Body

{
  "refreshToken": "<REFRESH_TOKEN>"
}

Response Body

{
  "accessToken": "<NEW_ACCESS_TOKEN>",
  "refreshToken": "<NEW_REFRESH_TOKEN>"
}

4. Forgot Password

Initiates and confirms password reset flow.

Environment Variables

IAM_OTP_EXPIRY: OTP expiry time (default: 10 mins).

4.1 Initiate Forgot Password

Starts the password reset process and sends a reset token to the user.

Endpoint

POST /api/iam/initiate/forgot-password

Headers

Content-Type: application/json

Request Body

{
  "email": "[EMAIL]",
  "username": "string"
}

Response Body

{
  "status": "success",
  "message": "Password reset token sent",
  "data": {
    "user": {
      "email": "[EMAIL]",
      "username": "string"
    }
  }
}

4.2 Confirm Forgot Password

Completes the password reset process with the verification token and new password.

Endpoint

POST /api/iam/confirm/forgot-password

Headers

Content-Type: application/json

Request Body

{
  "username": "string",
  "email": "[EMAIL]",
  "verificationToken": "string",
  "password": "[NEW_PASSWORD]"
}

Response Body

{
  "status": "success",
  "message": "Forgot password confirmed.",
  "error": "",
  "errorCode": "",
  "data": {}
}

5. Change Password

Changes the password for an existing user.

Endpoint

POST /api/iam/change-password

Headers

Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

Request Body

{
  "id": 0,
  "email": "[EMAIL]",
  "currentPassword": "[CURRENT_PASSWORD]",
  "newPassword": "[NEW_PASSWORD]"
}

6. Get User Info

Retrieve logged-in user info.

Endpoint

GET /api/iam/me

Headers

Authorization: Bearer <ACCESS_TOKEN>

Response Body

{
  "user": {
    "email": "[EMAIL]",
    "username": "[EMAIL]",
    "roles": ["Admin"]
  },
  "accessToken": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>"
}

7. Logout

Invalidate the current session.

Endpoint

POST /api/iam/logout

Headers

Content-Type: application/json

Request Body

{
  "refreshToken": "<REFRESH_TOKEN>",
  "allDevices": false
}

refreshToken is required. Set allDevices to true to revoke refresh tokens for every device belonging to the user. Omit it or set it to false to sign out only the session that issued this refresh token.

Response Body

{
  "message": "Logged out successfully"
}

After successful password authentication, the client receives an access token and refresh token in the JSON response. Use the access token in the Authorization: Bearer <ACCESS_TOKEN> header for protected APIs. Use the refresh token only with the refresh endpoint, and store it as a sensitive credential rather than regular client-side state.

Password

On this page