Log In with Email and Password via POST /auth/login

Authenticate with email and password to receive a session cookie. Brute-force protection locks the account after 10 failed attempts for 15 minutes.

Logging in authenticates you with your email and password and sets an HttpOnly session cookie on the response. All subsequent authenticated API calls rely on that cookie being present. The endpoint also returns your account’s email verification status so your UI can prompt for verification if needed.

Endpoint

POST https://api.example.com/api/v1/auth/login

This endpoint is public — no existing session or CSRF token is required.

Request Body

email · string · required

The email address associated with your account.

password · string · required

Your account password.

Example Request

cURL

curl -i -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "[e-mail]",
    "password": "S3cure!Pass"
  }'

Success Response — 200 OK

The session cookie is set and your account details are returned.

{
  "success": true,
  "data": {
    "public_id": "usr_01H",
    "email_verified": true
  }
}

success · boolean

Always true for successful responses.

data · object

Show data fields

public_id · string

Opaque public identifier for your account, prefixed usr_. Use this to identify the logged-in user in your application.

email_verified · boolean

true if you have completed email verification, false otherwise. Some API features may require a verified email.

Brute-force lockout: After 10 consecutive failed login attempts the account is locked for 15 minutes. During the lockout period every attempt — including a correct password — returns 429 Too Many Requests. Wait for the cooldown to expire before trying again. Do not implement automated retry loops that could trigger or extend the lockout.

Error Responses

Status	Meaning	When it occurs
401 Unauthorized	Invalid credentials	The email is not registered, the password is wrong, or the account combination could not be verified. The response deliberately avoids distinguishing between “email not found” and “wrong password” to prevent enumeration.
403 Forbidden	Account not accessible	The account has been suspended by an administrator or has been deleted. Contact support if you believe this is an error.
429 Too Many Requests	Rate limited / locked out	Either the per-IP rate limit was hit, or 10 failed attempts have triggered a 15-minute account lockout.

Example 401 Invalid Credentials

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "invalid email or password"
  }
}

Example 403 Suspended Account

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "account is suspended"
  }
}

Example 429 Lockout

{
  "success": false,
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "too many failed attempts, account locked for 15 minutes"
  }
}

Next Steps

After a successful login, fetch a CSRF token before calling any state-changing endpoint:

Get a CSRF Token

Required before any POST, PATCH, or DELETE request.

View Current Session

Call GET /auth/session to confirm your session is active.