Skip to main content
POST
/
api
/
auth
/
login
Login
curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>",
  "totpCode": "<string>"
}
'
{
  "success": true,
  "error": "<string>",
  "details": {}
}

​
Overview

Authenticates a user with username and password credentials. On successful authentication, the API creates an encrypted session cookie (crocante_session) that is used for subsequent authenticated requests. The endpoint acts as a Backend-for-Frontend (BFF) proxy, forwarding credentials to the backend authentication service and storing the resulting access token in a secure, HTTP-only cookie.

​
Request

​
username
string
required
The user’s username or email address
​
password
string
The user’s password. Optional for certain authentication flows
​
totpCode
string
Time-based one-time password (TOTP) code for two-factor authentication. Required if 2FA is enabled for the user

​
Request Example

{
  "username": "[email protected]",
  "password": "securePassword123",
  "totpCode": "123456"
}

​
Response

​
Success Response (200)

On successful authentication, the API returns a success indicator and sets the session cookie.
​
success
boolean
Always true on successful login
{
  "success": true
}
The response includes a Set-Cookie header with the following attributes:
  • Name: crocante_session
  • Value: Encrypted session payload containing the access token and issuance timestamp
  • Max-Age: 300 seconds (5 minutes)
  • HttpOnly: true (prevents JavaScript access)
  • Secure: true in production (HTTPS only)
  • SameSite: Strict (CSRF protection)
  • Path: /

​
Error Responses

​
error
string
A human-readable error message describing what went wrong
​
details
object
Validation error details when request format is invalid

​
400 Bad Request

Returned when the request body fails validation. 
{
  "error": "Invalid request",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "username": ["Username is required"]
    }
  }
}

​
401 Unauthorized

Returned when authentication credentials are invalid. 
{
  "error": "Login failed"
}

​
500 Internal Server Error

Returned when an unexpected error occurs during authentication. 
{
  "error": "Login failed"
}

​
Authentication Flow

  1. Client submits credentials to /api/auth/login
  2. BFF validates request format using Zod schema
  3. BFF forwards credentials to backend authentication service
  4. Backend validates credentials and returns access token
  5. BFF encrypts token with issuance timestamp
  6. BFF sets encrypted session cookie and returns success response
  7. Client automatically includes cookie in subsequent requests

​
Security Considerations

  • Access tokens are never exposed to client JavaScript
  • Session cookies are encrypted using AES-256-GCM
  • Cookies are HTTP-only to prevent XSS attacks
  • Strict SameSite policy prevents CSRF attacks
  • Sessions expire after 5 minutes of inactivity
  • Secure flag ensures HTTPS-only transmission in production

​
Code Example

import { LoginService } from '@/services/api/auth/login-service';

try {
  const result = await LoginService.login({
    username: '[email protected]',
    password: 'securePassword123',
    totpCode: '123456' // Optional, for 2FA
  });
  
  console.log('Login successful:', result.success);
  // Session cookie is automatically stored by browser
} catch (error) {
  console.error('Login failed:', error);
}

curl -X POST https://api.crocante.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "securePassword123"
  }' \
  -c cookies.txt

Build docs developers (and LLMs) love

Get started for freeTalk to us