Skip to main content

POST User Login

Authenticates a user and returns a session token for subsequent API requests.

Overview​

This endpoint is the primary method for user authentication in the VOLO API. After successful authentication, you'll receive a session token that must be included in the x-user-credential header for all subsequent requests that require user-based authentication.

Resource URL​

https://api.volo-access.com/v1/business/user/login

Authentication​

This endpoint requires application authentication only:

  • x-nonce-token: Required
  • x-app-token: Required
  • x-user-credential: Not required (this is what you're getting)

Request Body​

The request must include a JSON object with user credentials:

ParameterTypeRequiredDescription
usernameStringYesThe user's username
passwordStringYesThe user's password

Example Request Body​

{
  "username": "john.doe@company.com",
  "password": "securepassword123"
}

Response​

Success Response (200 OK)​

Returns a LoginResponse object with session information:

ParameterTypeDescription
sessionTokenStringThe session token to use in x-user-credential header
expirationDateDateTimeWhen the session token expires (ISO 8601 format)
loginMessageStringAny additional login message (may be null)

Example Success Response​

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expirationDate": "2024-01-15T14:30:00.000Z",
  "loginMessage": "Login successful"
}

Error Responses​

400 Bad Request​

Returned when username or password is missing:

{
  "applicationMessage": "Missing required field: username",
  "consumerMessage": "Please provide both username and password"
}

401 Unauthorized​

Returned for invalid credentials or locked accounts:

{
  "applicationMessage": "Invalid credentials provided",
  "consumerMessage": "Invalid username or password. Please try again."
}

500 Internal Server Error​

Returned for server-side errors:

{
  "applicationMessage": "Database connection failed",
  "consumerMessage": "An error occurred during login. Please try again later."
}

Example Request​

POST https://api.volo-access.com/v1/business/user/login
Content-Type: application/json
x-nonce-token: MDU4ZmQ5Y2EtNTExNi00N2E0LWI0Y2EtNjM1YWRjZTZjYmNi
x-app-token: d1d0ecac-3cca-48ef-a4c3-83005c6376ca

{
  "username": "john.doe@company.com",
  "password": "securepassword123"
}

Usage Notes​

  • Session Duration: Session tokens typically expire after a period of inactivity or at a specific time
  • Token Storage: Store the session token securely and include it in the x-user-credential header for subsequent requests
  • Token Renewal: Use the session renewal endpoint to extend the session if needed
  • Security: Never log or expose session tokens in client-side code
  • Multiple Sessions: A user can have multiple active sessions simultaneously