Skip to main content

Authentication

All API endpoints require authentication via a Bearer Token. Include the access token in the Authorization header of every request:

Authorization: Bearer <access_token>

🔑 First-Time Login​

If this is your first time accessing the API, follow this two-step flow to set your permanent credentials.

Step 1 — Sign In​

Call the Sign In endpoint with your credentials.

Request example:

curl -X POST "/api/v1/auth/admin/confirm-first-password" ^
  -H "Content-Type: application/json" ^
  -d "{\"username\":\"your_email\",\"password\":\"your_temporary_password\"}"

A successful response returns a session that you must use in the next step.

{
  "challengeName": "NEW_PASSWORD_REQUIRED",
  "session": "session-code",
  "email": "your_email"
}

Step 2 — Confirm First Password​

Call the Confirm First Password endpoint using the session received above.

Request example:

curl -X POST "/api/v1/auth/admin/confirm-first-password" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_email",
    "password": "your_new_password",
    "session": "session_received_above"
  }'

A successful response returns:

{
    "accessToken": "your_access_token",
    "refreshToken": "your_refresh_token"
    "expiresIn": "expiration_time_in_ms"
    "idToken": "id_token"
}
  • Include accessToken in all API requests via the Authorization header
  • Store refreshToken securely to refresh your session without re-authenticating

Subsequent Logins​

After completing the first-time setup, use the Sign In endpoint directly on every login.

Request example:

curl -X POST "/api/v1/auth/admin/sign-in" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

A successful response returns:

{
    "accessToken": "your_access_token",
    "refreshToken": "your_refresh_token"
    "expiresIn": "expiration_time_in_ms"
    "idToken": "id_token"
}
  • Include accessToken in all API requests via the Authorization header
  • Store refreshToken securely to refresh your session without re-authenticating

⏳ Token Expiration & Refresh​

Access tokens have a limited lifetime. When a token expires, your requests will return an error:

{
  "error": "TokenExpired",
  "message": "Access token expired",
  "statusCode": 401
}

. To get a new access token without logging in again, call the Refresh Session endpoint with your refresh token.

Request example:

curl -X POST "/api/v1/auth/admin/refresh-session" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "<your_refresh_token>"
  }'

A successful response returns a new accessToken (and typically a new refreshToken).

🔐 Independent Authentication per User​

Each user in the system — whether a store, supervisor or a branch — must handle authentication independently.

For more information about branches and supervisors, see:

Best Practices​

  • Store tokens securely. Never hardcode tokens in source code or expose them in client-side applications.
  • Refresh proactively. Refresh your access token before it expires to avoid interruptions.
  • Rotate refresh tokens. Treat refresh tokens as sensitive credentials — store them in a secure, server-side location
  • Use strong passwords. Ensure your password meets security requirements (minimum length, mixed case, numbers, and special characters) to prevent brute-force attacks.