Authentication & Account Management
Secure your API requests with JWT Bearer tokens. Manage user accounts, sessions, and credentials with our comprehensive authentication system.
Authentication Method
JWT Bearer Token
All API endpoints require JWT Bearer token authentication
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...✓ Access token expires in 30 minutes
✓ Refresh token valid for 7 days
✓ Contains account metadata (account_id, account_type, rate_limit)
✓ Automatic token refresh supported
Login
/api/v1/auth/loginAuthenticate with email and password to receive fresh JWT tokens. Use this when your access token expires or when logging in from a new device.
▶HTTP Headers
About This Endpoint
Authenticate an existing account using email and password credentials to obtain fresh JWT access and refresh tokens. This endpoint is used for initial login sessions, re-authentication after token expiration, or when accessing the platform from a new device or application. The returned access token is valid for 30 minutes and the refresh token for 7 days, enabling secure, stateless authentication across all API endpoints.
Common Use Cases
- User authentication when launching your application or web portal
- Re-establishing sessions after access tokens expire
- Logging in from multiple devices or browser sessions
Security Best Practices
- Store tokens securely using encrypted storage or secure cookies
- Implement automatic token refresh before expiration
- Use HTTPS for all authentication requests
{
"email": "user@example.com",
"password": "P@ssw0rd123!"
}Response Example
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "def502004a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6...",
"token_type": "Bearer",
"expires_in": 1800
}Token Lifetimes:
- Access Token: 30 minutes (1800 seconds)
- Refresh Token: 7 days
Get Current User Info
/api/v1/auth/meRetrieve the current authenticated user's account information using their JWT token.
▶HTTP Headers
About This Endpoint
Fetch complete account details for the currently authenticated user by validating their JWT access token. This endpoint decodes the bearer token to identify the user and returns their profile information including account type, contact details, company information, and account status. It's essential for verifying active sessions, displaying user profiles in dashboards, and confirming account permissions before performing sensitive operations.
Common Use Cases
- Loading user profile data when rendering application dashboards or settings pages
- Verifying account status and type before displaying feature-specific UI components
- Confirming session validity after page refreshes or application restarts
Response Details
- Returns account_type field to distinguish between main accounts and sub-accounts
- The is_active flag indicates whether the account can make API calls
- No request body required—authentication comes solely from the JWT token
Response Example
{
"account_id": "MA_2210JXXN",
"name": "Your Company Name",
"email": "admin@yourcompany.com",
"phone": "+1234567890",
"company": "Your Company Inc",
"account_type": "account",
"is_active": true,
"created_at": "2025-10-12T10:00:00.000Z"
}Refresh Access Token
/api/v1/auth/refreshExchange your refresh token for a new access token when the current one expires (after 30 minutes).
▶HTTP Headers
About This Endpoint
Obtain a fresh access token without requiring the user to re-enter their credentials by exchanging a valid refresh token. Access tokens expire after 30 minutes for security, while refresh tokens remain valid for 7 days. This mechanism enables seamless, uninterrupted API access for your applications by automatically renewing authentication in the background before the access token expires, eliminating the need for repeated user logins during active sessions.
Common Use Cases
- Implementing automatic token refresh in SPAs or mobile apps to maintain user sessions
- Background processes that need continuous API access beyond 30 minutes
- Recovering from 401 Unauthorized errors by silently refreshing expired tokens
Implementation Best Practices
- Refresh proactively 5-10 minutes before expiration rather than waiting for failures
- Store refresh tokens securely using encrypted storage (never in localStorage)
- Handle refresh failures by redirecting users to the login page
{
"refresh_token": "def502004a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6..."
}Response Example
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 1800
}Pro Tip: Implement automatic token refresh in your application to maintain seamless user sessions. Refresh the access token before it expires.
Change Password
/api/v1/auth/change-passwordChange account password. Requires current password verification. All existing refresh tokens will be invalidated.
▶HTTP Headers
About This Endpoint
Update your account password by providing both the current password for verification and the desired new password. As a critical security measure, successfully changing your password immediately invalidates all existing refresh tokens across all devices and sessions, forcing re-authentication everywhere. This prevents unauthorized access if your old password was compromised and ensures that only sessions using the new credentials remain active after the password change.
Common Use Cases
- User-initiated password updates from account security settings
- Enforcing password rotation policies for compliance requirements
- Responding to suspected security breaches by immediately securing the account
Security Implications
- All active sessions on all devices will be logged out immediately
- Current access token remains valid until its 30-minute expiration
- User must log in again on all devices with the new password
{
"current_password": "P@ssw0rd123!",
"new_password": "N3wP@ssw0rd456!"
}Response Example
{
"message": "Password changed successfully",
"tokens_invalidated": true
}Security Note: Changing your password will invalidate all existing refresh tokens. You'll need to login again on all devices.
Logout
/api/v1/auth/logoutLogout current user and invalidate their refresh token. The access token remains valid until it expires.
▶HTTP Headers
About This Endpoint
Securely terminate the current user session by invalidating the refresh token associated with their access token. While the current access token technically remains valid until its natural 30-minute expiration, the refresh token is immediately revoked, preventing any future token renewals. This ensures that once the access token expires, the user cannot obtain a new one without logging in again, effectively ending their authenticated session within 30 minutes maximum.
Common Use Cases
- User-initiated logout from web applications or mobile apps
- Ending sessions when users switch accounts or log out from shared devices
- Security best practice when users finish working with sensitive data
Important Behavior
- Logout only affects the current device/session, not all user sessions
- Access token can still be used for up to 30 more minutes after logout
- Client applications should discard both tokens immediately after logout
Response Example
{
"message": "Logged out successfully"
}