Login

Shared API

Authenticate a user with email and password.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Parameters
• Response
• Error Responses
• Example

Endpoint

POST /api/v1/auth/login

Headers

Header	Required	Description
Content-Type	Yes	application/json
x-device-fingerprint	No	JSON string with device fingerprinting data

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "workspace_id": 1,
  "remember_me": false
}

Parameters

Field	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password
workspace_id	integer	No	Target workspace ID
remember_me	boolean	No	Extend session to 30 days (default: false, 24 hours)

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "email": "user@example.com",
    "display_name": "John Doe",
    "is_verified": true
  },
  "message": "Login successful"
}

MFA Required (200)

If MFA is enabled for the user:

{
  "success": true,
  "data": {
    "temporary_token": "temp_token_here",
    "mfa_required": true,
    "message": "MFA verification required"
  },
  "message": "MFA verification required"
}

Email Verification Required (200)

If email is not verified:

{
  "success": true,
  "data": {
    "temporary_token": "temp_token_here",
    "email_verification_required": true,
    "message": "Email verification required"
  },
  "message": "Email verification required"
}

Error Codes

Status	Code	Description
401	INVALID_CREDENTIALS	Invalid email or password
403	EMAIL_NOT_VERIFIED	Email address not verified
422	VALIDATION_ERROR	Request validation failed
429	RATE_LIMITED	Too many login attempts (5 per 15 minutes)

Rate Limiting

• Limit: 5 attempts per 15 minutes per IP
• Response: 429 Too Many Requests
• Rate limit applies per email address

Features

• Automatic device fingerprinting
• Session creation
• Audit logging
• Returns OAuth2 tokens (access + refresh)
• Supports "remember me" functionality (30 days vs 24 hours)
• MFA integration
• Email verification check

Example

curl -X POST https://api.rivergen.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "x-device-fingerprint: {\"screen\":\"1920x1080\",\"timezone\":\"UTC\"}" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "remember_me": true
  }'

Related Endpoints

• MFA OTP Generate - Generate MFA code
• MFA Verify - Complete MFA verification
• Verify Email - Verify email address