Skip to main content

​
POST /api/auth/login

Authenticates a user with their username and password credentials. Supports two-factor authentication (TOTP) when enabled for the user.

​
Request Body

​
username
string
required
The user’s username (trimmed, minimum 1 character)
​
password
string
required
The user’s password (trimmed, minimum 1 character)
​
code
string
TOTP code for two-factor authentication. Required if the user has TOTP enabled and this is a second login request.

​
Headers

​
x-zipline-client
string
Optional client identifier for tracking the source of the request

​
Response

​
user
object
The authenticated user object (only returned on successful login)
​
totp
boolean
Indicates that TOTP is enabled for this user. When true, the client should prompt for a TOTP code and make a second request with the code parameter.

​
Rate Limiting

This endpoint is rate limited to 2 requests per second.

​
Authentication Flow

  1. Initial request: Send username and password
  2. TOTP enabled: If the user has TOTP enabled, the response will be { "totp": true }
  3. Second request: Make another request with the same credentials plus the code parameter
  4. Success: Returns the user object and establishes a session

​
Error Responses

  • 400 Bad Request - Invalid username or password
  • 400 Bad Request - Invalid code (when TOTP code is incorrect)
  • 429 Too Many Requests - Rate limit exceeded

​
Example Request

curl -X POST https://your-zipline-instance.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "securepassword123"
  }'

​
Example Response (No TOTP)

{
  "user": {
    "id": "clx1234567890",
    "username": "johndoe",
    "role": "USER",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-03-01T14:22:00.000Z",
    "view": {},
    "oauthProviders": [],
    "totpSecret": null,
    "quota": null,
    "avatar": null,
    "token": "zpl_abc123def456ghi789"
  }
}

​
Example Response (TOTP Enabled)

{
  "totp": true
}

​
Example Request with TOTP Code

curl -X POST https://your-zipline-instance.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "securepassword123",
    "code": "123456"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us