Password
Information about password-based authentication APIs
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.
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.
Environment Variables
IAM_PASSWORD_REGISTRATION_ENABLED: Enables/disables registration.IAM_ALLOW_PUBLIC_REGISTRATION: Allows public registration when set totrue.
Headers
Content-Type: application/jsonRequest 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
Log in and receive access and refresh tokens.
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/jsonRequest Body
{
"email": "[EMAIL]",
"username": "[EMAIL]",
"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.
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).
Request
POST /api/iam/initiate/forgot-passwordHeaders
Content-Type: application/jsonRequest Body
{
"email": "[EMAIL]",
"username": "string"
}Response Body
{
"status": "success",
"message": "Password reset token sent",
"data": {
"user": {
"email": "[EMAIL]",
"username": "string"
}
}
}Request
POST /api/iam/confirm/forgot-passwordRequest Body
{
"username": "string",
"email": "[EMAIL]",
"verificationToken": "string",
"password": "[NEW_PASSWORD]"
}5. Change Password
Request
POST /api/iam/change-passwordRequest Body
{
"id": 0,
"email": "[EMAIL]",
"currentPassword": "[CURRENT_PASSWORD]",
"newPassword": "[NEW_PASSWORD]"
}6. Get User Info
Retrieve logged-in user info.
Response Body
{
"user": {
"email": "[EMAIL]",
"username": "[EMAIL]",
"roles": ["Admin"]
},
"accessToken": "<ACCESS_TOKEN>",
"refreshToken": "<REFRESH_TOKEN>"
}7. Logout
Invalidate the current session.
Response Body
{
"message": "Logout successful"
}