Login & Logout

Endpoints for creating and terminating user sessions.

POST /api/login/{domain}

Authenticate a user and create a new session.

Authentication: Tenant-level (no user session required)

Path Parameters:

Parameter	Type	Description
domain	string	Authentication domain (e.g., local, SAML provider ID)

Request Body:

Field	Type	Required	Description
username	string	Yes	Username (case-insensitive)
password	string	Yes (for local)	User password
mfaConfig	object	No	MFA configuration if enrolled
mfaConfig.loginTicket	string	No	Login ticket from MFA flow
mfaConfig.code	string	No	MFA verification code

Query Parameters:

Parameter	Type	Default	Description
redirect	boolean	false	Redirect to URL after login

Example Request (Local Auth):

{
  "username": "admin",
  "password": "secure-password"
}

Example Request (MFA Verification):

{
  "username": "admin",
  "mfaConfig": {
    "loginTicket": "jwt-login-ticket",
    "code": "123456"
  }
}

Response:

{
  "user": {
    "username": "admin",
    "displayName": "Administrator",
    "email": "admin@example.com",
    "domain": "local",
    "enabled": true,
    "superuser": true,
    "_links": {
      "self": { "href": "/api/users/admin" }
    }
  },
  "sid": "abc123-session-id",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "wsToken": "ws-token-here",
  "locale": "en-US",
  "lang": "en"
}

MFA Response (Setup Required):

{
  "mfaConfigs": [
    {
      "id": "totp",
      "name": "Authenticator App",
      "setupComponent": "totp-setup",
      "qrCode": "data:image/png;base64,...",
      "secret": "BASE32SECRET"
    }
  ],
  "loginTicket": "jwt-ticket-for-mfa-completion"
}

MFA Response (Verification Required):

{
  "loginTicket": "jwt-ticket-for-mfa-verification",
  "verifyConfig": {
    "component": "totp-verify"
  }
}

Error Responses:

• 401 Unauthorized - Invalid credentials, account locked, or password expired
• 400 Bad Request - Invalid domain or missing required fields

Pre-blocks:

• Login ticket verification (if provided)
• Domain lookup and validation
• MFA authenticator check
• Passport strategy authentication
• Domain coercion and user validation
• License check (user count limit)
• User find-or-create
• MFA setup or verification
• Session creation
• Session credentials generation

Timeout: 2 minutes

Account Lockout

Failed login attempts increment a counter. After exceeding the configured limit (tenant setting loginAttemptsAllowed), the account is locked for the configured lockoutTime (in minutes).

Password Expiration

If a user's password has expired, they will receive a 401 error with message "Password must be reset". Use the forgot password flow to reset.

---

GET /api/login/{domain}

Authenticate via GET request (typically for SSO flows).

Authentication: Tenant-level

Path Parameters:

Parameter	Type	Description
domain	string	Authentication domain

Query Parameters:

Parameter	Type	Default	Description
redirect	boolean	false	Redirect to URL after login

Response:

Same as POST endpoint or redirect to SSO provider.

---

GET /api/login/{domain}/sso

Initiate SSO authentication flow (SAML).

Authentication: Tenant-level

Path Parameters:

Parameter	Type	Description
domain	string	SAML domain ID

Query Parameters:

Parameter	Type	Description
redirectTo	string	Relative path to redirect to after successful login

Response:

302 Redirect to SAML IdP entry point

Cookie Set:

Sets a short-lived cookie with redirect information that persists across the SAML roundtrip.

Example:

GET /api/login/saml-domain/sso?redirectTo=/datasets

---

POST /api/logout

Terminate the current session and clear cookies.

Authentication: Optional (mode: try)

Pre-blocks: Current session lookup

Response:

204 No Content

Side Effects:

• Destroys the current session in database
• Clears session cookie
• If the session had a parent (impersonation), sets cookie to parent session

Example:

curl -X POST https://app.example.com/api/logout \
  -H "Cookie: sid=session-id-here"

Impersonation Support

If the current session is an impersonated session (has a parent), logging out will restore the parent session instead of fully logging out.