Skip to main content

​
Login and Get Roles

Authenticates a user with email and password, returning all available roles for the account.

​
Request Body

​
email
string
required
User’s registered email address
​
password
string
required
User’s password

​
Response

​
accountId
string (uuid)
Unique identifier for the user account
​
email
string
User’s email address
​
roles
array<string>
List of roles assigned to this account (e.g., [“Customer”], [“Customer”, “Seller”])

​
Response Codes

  • 200 OK - Authentication successful
  • 400 Bad Request - Invalid request format
  • 403 Forbidden - Account locked or disabled
  • 404 Not Found - Email not found or incorrect password
  • 500 Internal Server Error - Server error

​
Examples

curl -X POST "https://your-server.com/api/account/roles" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

​
Success Response Example

{
  "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "[email protected]",
  "roles": ["Customer", "Seller"]
}

​
Error Response Examples

Invalid Credentials (404 Not Found): 
"Invalid email or password"
Account Locked (403 Forbidden): 
"Account has been locked due to multiple failed login attempts"

​
Get Token by Role

After receiving available roles, select a specific role to get a JWT token.

​
Request Body

​
accountId
string (uuid)
required
Account ID received from the login/roles endpoint
​
role
string
required
Role to authenticate as (must be one of the roles returned from /api/account/roles)

​
Response

​
token
string
JWT authentication token for the selected role

​
Response Codes

  • 200 OK - Token generated successfully
  • 400 Bad Request - Invalid role or account ID
  • 403 Forbidden - User doesn’t have the requested role
  • 404 Not Found - Account not found

​
Examples

curl -X POST "https://your-server.com/api/account/token" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "role": "Customer"
  }'

​
Success Response Example

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYTYiLCJyb2xlIjoiQ3VzdG9tZXIiLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

​
Next Steps

After successful login:
  1. Store the JWT token securely
  2. Include the token in the Authorization header for subsequent requests
  3. Use role-specific endpoints based on your selected role
Users can have multiple roles. Call the token endpoint again with a different role to switch contexts.

Build docs developers (and LLMs) love

Get started for freeTalk to us