Authentication

Login, logout, and session management

Authenticate user with email and password

post

Authenticates a user using email and password credentials. On success, establishes a session and returns an authentication token with optional redirect URL.

Email Verification Requirement: When GUEST_USER_REGISTRATION_REQUIRES_EMAIL_VERIFICATION is enabled (Dynamic Configuration), login is blocked for users who:

1. Were created as guest users during checkout (have verification_required attribute set to true in their user profile)

2. Have not yet verified their email address

These users must click the verification link sent to their email before they can log in. The error message will be: "Please verify your email address before login."

Throttling scope: login.

Body

application/json

emailstring · emailRequired

User email address

passwordstring · passwordRequired

User password

Responses

200

Login successful

application/json

400

Invalid credentials or email not verified

429

Too many login attempts (throttled)

post

/users/login

HTTPcURLJavaScriptPython

POST /users/login HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "email": "[email protected]",
  "password": "password"
}

{
  "key": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
  "redirect_url": null
}

Authenticate user with phone and OTP code

post

Authenticates a user using phone number and SMS verification code. This is a two-step process:

Step 1 - Request OTP: Send phone without code. System validates phone exists, sends SMS verification code, and stores confirmation data in session. Returns empty 200 response on success.

Step 2 - Verify and Login: Send phone with code. If valid, user is authenticated and returns authentication token with redirect URL.

Code Validation:

• Code must be 4-20 characters

• Code expiration controlled by SMS_OTP_EXPIRE_TIME setting

• Invalid or expired codes return 406 status

Throttling scope: login.

Body

application/json

phonestring · max: 16Required

Phone number that matches an existing active user in the system. Phone number must pass the configured phone regex validator. Returns 400 error if no user exists with this phone number.

Example: 05355555555

codestring · min: 4 · max: 20Optional

SMS verification code received in Step 1.

• Omit this field on first request to receive OTP via SMS
• Include this field with the received code to complete login
• Code expiration is controlled by SMS_OTP_EXPIRE_TIME setting

Example: 123456

Responses

200

• With valid code: Login successful, returns authentication token
• Without code: OTP sent successfully (empty response body)

application/json

Responseone of

or

objectOptional

Empty response when OTP is sent

400

Validation errors:

• Phone number doesn't exist in system
• Phone number format is invalid
• Code length is invalid (less than 4 characters)

406

• Incorrect OTP code
• OTP code expired

429

Too many login attempts (throttled)

post

/users/otp-login

HTTPcURLJavaScriptPython

POST /users/otp-login HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "phone": "05355555555",
  "code": "123456"
}

{
  "key": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
  "redirect_url": null
}

End user session

post

Terminates the current user session and clears session data.

Redirect Behavior:

• If referrer starts with the account index path (e.g., /users/), redirects to home page

• Otherwise, uses the next parameter or default logout redirect URL

• For non-existent URLs in next, falls back to adapter's logout redirect

Audit Logging: Creates an audit event recording the logout action with user information, client type, and browser agent.

Can be called by anonymous users (no error, simply redirects).

Header parameters

X-CSRFTokenstringRequired

CSRF token for state-changing requests

Body

application/x-www-form-urlencoded

referrerstringOptional

URL referrer. If starts with account index path (reverse of 'account-index'), redirects to home page.

Example: /users/profile/

nextstringOptional

URL to redirect after logout. Must be a valid resolvable path. Falls back to adapter's logout redirect if invalid.

Example: /basket/

Responses

302

Redirect to specified or default logout URL

post

/users/logout/

HTTPcURLJavaScriptPython

POST /users/logout/ HTTP/1.1
Host: sandbox.akinon.com
X-CSRFToken: text
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 48

"referrer='/users/profile/'&next='/basket/'"

302

Redirect to specified or default logout URL

No content

Generate one-time login token (Admin Only)

post

Generates a one-time login token for passwordless authentication. This is an administrative endpoint used to create secure login links that can be sent to users via email or other channels.

Authentication Required: Admin users only.

Flow:

1. Admin provides user ID and secret key

2. System generates one-time token

3. Returns redirect URL with embedded token

4. Admin sends this URL to the user (e.g., via email)

5. User clicks URL and is authenticated at /users/passwordless-login/{token}/

Token Properties:

• One-time use only (deleted after successful login)

• Time-limited (expires after 5 minutes)

Secret Key: The secret_key parameter is used for token generation and must be provided again when the token is used at the GET endpoint. This adds an extra layer of security beyond the token itself.

Authorizations

AdminAuthentication

AuthorizationstringRequired

Admin authentication using Token Authentication. Requires user to have admin/staff privileges. Include token in Authorization header as: Authorization: Token <token>

Body

application/json

userintegerRequired

User ID for whom to generate the one-time login token. Must be an active user in the system.

Example: 123

secret_keystringRequired

Secret key used for token generation and validation. This same key must be provided when using the generated token at /users/passwordless-login/{token}/ endpoint.

Example: user-login-secret

Responses

200

Token generated successfully

application/json

400

Validation errors:

• User ID doesn't exist
• User is not active
• Missing required fields

401

Authentication required

403

Admin permission required

post

/api/v1/passwordless-login/

HTTPcURLJavaScriptPython

POST /api/v1/passwordless-login/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "user": 123,
  "secret_key": "user-login-secret"
}

{
  "redirect_url": "/users/passwordless-login/1a2b3c4d5e6f7-8g9h0i1j2k3l4m5n6o7p/"
}

Authenticate via one-time token link

get

Validates a one-time token and automatically logs in the user. This endpoint is typically accessed via email link sent by administrators.

Flow:

1. Administrator generates one-time token via admin API

2. Token is sent to user via email/link

3. User clicks link with token in URL

4. System validates token and completes login

5. User is redirected to specified URL or home

Token Validation:

• Token must exist and not be expired

• Token expires after 5 minutes

• After successful login, token is deleted (single use)

Invalid Token Handling:

• Expired or invalid tokens redirect to home page

• No error message is shown (silent fail for security)

Path parameters

tokenstringRequired

One-time login token generated by the admin API.

Example: 1a2b3c4d5e6f7-8g9h0i1j2k3l4m5n6o7p

Query parameters

userintegerRequired

User ID for token validation

Example: 123

secret_keystringRequired

Secret key used for token generation and validation. Must match the key used when creating the token.

Example: user-login-secret

nextstringOptional

URL to redirect after successful login. Defaults to home page if not provided.

Example: /dashboard/

Responses

302

• Valid token: User logged in, redirected to 'next' URL or home
• Invalid/expired token: Redirected to home page

get

/users/passwordless-login/{token}/

HTTPcURLJavaScriptPython

GET /users/passwordless-login/{token}/?user=1&secret_key=text HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

302

• Valid token: User logged in, redirected to 'next' URL or home
• Invalid/expired token: Redirected to home page

No content

Authenticate via auth token (API)

post

Authenticates user using their existing authentication token via API call. This is designed for programmatic/mobile app access.

Important: This endpoint uses authentication tokens (from standard login), NOT one-time tokens. For one-time token authentication, use the GET endpoint /users/passwordless-login/{token}/ with tokens generated from /api/v1/passwordless-login/ (admin endpoint).

Flow:

1. User must already have an authentication token (obtained from previous login)

2. Client sends user ID and token

3. System validates token exists for that user

4. User is logged in via session authentication

5. Returns success status (no redirect, pure API response)

Token Validation:

• Token must exist and be associated with the specified user

• Token is the user's permanent auth token (not a one-time token)

• Token is NOT deleted after login (can be reused)

Use Case: This endpoint allows mobile apps or API clients to establish a session using the token they received from standard login, enabling them to access session-based endpoints.

Body

application/json

userintegerRequired

User ID. Must be an active user in the system. Returns 400 if user doesn't exist or is inactive.

Example: 123

tokenstringRequired

User's authentication token. This is the same token returned from /users/login endpoint. Must match the token associated with the specified user.

Example: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b

Responses

200

Login successful, session established

No content

400

Validation errors:

• User ID doesn't exist or user is not active
• Token doesn't exist for the specified user
• Token doesn't match user's auth token

post

/users/passwordless-login-with-token/

HTTPcURLJavaScriptPython

POST /users/passwordless-login-with-token/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "user": 123,
  "token": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b"
}

No content