Manage Access Tokens
To securely access ImPAI’s private API endpoints, your business must first authenticate using the credentials provided during onboarding. This process uses the OAuth 2.0 Password Credentials Grant Type, ensuring only authorized users and applications can interact with sensitive financial services.
Credentials Required
ImPAI uses a standards-based OAuth 2.0 authentication flow.
This implementation follows the Resource Owner Password Credentials Grant to authenticate users directly using their username and password.
- Client ID: The unique identifier assigned to your application during onboarding
- Client Secret: The secret key associated with your Client ID (if required by your client configuration)
- Username: Your assigned login username
- Password: Your associated password
Upon successful authentication, you will receive an access token. This token must be included in the header of all subsequent API requests to authorize access.
1️⃣ Login – Receive an Access Token
Authenticates a user and returns access and refresh tokens for secure API access.
Request Structure
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
grant_type | String | Yes | Must be password |
client_id | String | Yes | Your assigned Client Id |
client_secret | String | Yes | Your Client Secret (required) |
username | String | Yes | Your login username |
password | String | Yes | Your password |
scope | String | No | Optional scope parameter |
Example Request:
POST /api/auth/v1/realms/{realm}/login
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&username=YOUR_USERNAME&password=YOUR_PASSWORD
Response Structure
🟢 Success — HTTP 200
HTTP 200 – OK responses for a successful login include:
| Field | Type | Description |
|---|---|---|
access_token | String | Bearer token for API authorization |
refresh_token | String | Token to obtain new access tokens |
token_type | String | Typically bearer |
expires_in | Integer | Token expiration time in seconds |
refresh_expires_in | Integer | Refresh token expiration in seconds |
Example:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600,
"refresh_expires_in": 86400
}
🔴 Error — HTTP 400
Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and indicate syntax issues or missing/invalid credentials with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🔴 Error — HTTP 401
Responses for HTTP 401 – Unauthorized errors are returned if validation or business checks fail and indicate missing/invalid credentials with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🟡 Error — HTTP 500
Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:
| Group | Description |
|---|---|
errorCode | Application-level error identifier (e.g. 500_INTERNAL_ERROR) |
message | Brief description such as "Time-out" or "Something went wrong" |
Example:
{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
Using the Access Token
Include the access token in the Authorization header for all subsequent API requests:
Authorization: Bearer {{access_token}}
2️⃣ Refresh your Token
When your access token expires, you can obtain a new one using the refresh token. This process ensures uninterrupted access to protected API endpoints without requiring the user to re-authenticate.
Used to refresh an existing access token using a valid refresh token.
Request Structure
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
grant_type | String | Yes | Must be refresh_token |
client_id | String | Yes | Your assigned Client ID |
client_secret | String | Yes | Your Client Secret (required) |
refresh_token | String | Yes | The refresh token received during login |
scope | String | No | Optional scope parameter |
Example Request:
POST /api/auth/v1/realms/{realm}/refresh
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN
Response Structure
🟢 Success — HTTP 200
HTTP 200 – OK responses for a successful token refresh include:
| Field | Type | Description |
|---|---|---|
access_token | String | Bearer token for API authorization |
refresh_token | String | Token to obtain new access tokens |
token_type | String | Typically bearer |
expires_in | Integer | Token expiration time in seconds |
refresh_expires_in | Integer | Refresh token expiration in seconds |
Example:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600,
"refresh_expires_in": 86400
}
🔴 Error — HTTP 400
Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and indicate syntax issues or an invalid refresh token with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🔴 Error — HTTP 401
Responses for HTTP 401 – Unauthorized errors are returned if validation or business checks fail and indicate an invalid refresh token with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🟡 Error — HTTP 500
Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:
| Group | Description |
|---|---|
errorCode | Application-level error identifier (e.g. 500_INTERNAL_ERROR) |
message | Brief description such as "Time-out" or "Something went wrong" |
Example:
{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
3️⃣ Logout from Session
To invalidate your session and tokens, use:
Request Structure
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
client_id | String | Yes | Your assigned Client ID |
client_secret | String | Yes | Your Client Secret (required) |
refresh_token | String | Yes | The refresh token to invalidate |
Example Request:
POST /api/auth/realms/{realm}/logout
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN
Response Structure
🟢 Success — HTTP 204
The HTTP 204 – No Content response signals a successful logout but does not contain any content.
🔴 Error — HTTP 400
Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and indicate syntax issues or missing/invalid credentials with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🔴 Error — HTTP 401
Responses for HTTP 401 – Unauthorized errors are returned if validation or business checks fail and indicate missing/invalid credentials with these error codes:
| Error Code | Description |
|---|---|
Username_Or_Password_Incorrect | The username or password provided is incorrect. |
Account_Not_Verified | The account is not yet authorized for API access. |
Account_Locked | The account is temporarily locked due to too many failed attempts. |
Account_Suppressed | The account is inactive or restricted. |
🟡 Error — HTTP 500
Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:
| Group | Description |
|---|---|
errorCode | Application-level error identifier (e.g. 500_INTERNAL_ERROR) |
message | Brief description such as "Time-out" or "Something went wrong" |
Example:
{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
When to Use Login vs. Refresh
Use the login endpoint when a user is signing in with their username and password for the first time or after their session has expired and both credentials are required.
Use the refresh endpoint when you already have a valid refresh token and want to obtain a new access token without prompting the user to re-enter their credentials. This helps maintain a seamless user experience by keeping sessions active without repeated logins, as long as the refresh token remains valid.