Skip to main content
POST
/
api
/
auth
/
login
Login User
curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>"
}
'
{
  "user": {
    "user.id": "<string>",
    "user.email": "<string>",
    "user.full_name": "<string>",
    "user.is_active": true,
    "user.is_verified": true,
    "user.created_at": {}
  },
  "tokens": {
    "tokens.access_token": "<string>",
    "tokens.refresh_token": "<string>",
    "tokens.token_type": "<string>",
    "tokens.expires_in": 123
  }
}

Overview

Authenticate a user with email and password credentials. Returns user information along with access and refresh tokens for subsequent authenticated requests.

Endpoint

POST /api/auth/login

Request Body

email
string
required
User’s registered email address.
password
string
required
User’s password.

Response

user
object
User information object.
user.id
UUID
Unique identifier for the user.
user.email
string
User’s email address.
user.full_name
string
User’s full name.
user.is_active
boolean
Whether the user account is active.
user.is_verified
boolean
Whether the user’s email has been verified.
user.created_at
datetime
Timestamp when the user account was created.
tokens
object
JWT tokens for authentication.
tokens.access_token
string
JWT access token for API requests. Include in Authorization: Bearer <token> header.
tokens.refresh_token
string
Refresh token used to obtain new access tokens when they expire.
tokens.token_type
string
Token type. Always "bearer".
tokens.expires_in
integer
Access token expiration time in seconds.

Example Request

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

Example Response

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "full_name": "John Doe",
    "is_active": true,
    "is_verified": false,
    "created_at": "2026-03-03T10:30:00Z"
  },
  "tokens": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "7x9kP3mN8qR2wV5tY1uZ4jH6fL0sA3bC",
    "token_type": "bearer",
    "expires_in": 1800
  }
}

JWT Token Format

The access token is a JWT containing the following payload:
{
  "sub": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "type": "access",
  "exp": 1709467800,
  "iat": 1709466000
}
  • sub: User ID (UUID)
  • email: User’s email address
  • type: Token type ("access")
  • exp: Expiration timestamp (Unix epoch)
  • iat: Issued at timestamp (Unix epoch)

Token Expiration

  • Access Token: Expires after 30 minutes (1800 seconds) by default
  • Refresh Token: Expires after 7 days by default
The refresh token is stored securely (SHA-256 hashed) along with device information and IP address for security tracking.

Error Responses

401 Unauthorized

Returned when email or password is incorrect.
{
  "detail": "Invalid email or password"
}

403 Forbidden

Returned when the user account is disabled.
{
  "detail": "User account is disabled"
}

500 Internal Server Error

Returned when login fails due to a server error.
{
  "detail": "Failed to login"
}

Security Notes

  • Passwords are verified using bcrypt
  • Refresh tokens are hashed with SHA-256 before storage
  • Device information (User-Agent) and IP address are tracked for security
  • Inactive users cannot login even with correct credentials

Build docs developers (and LLMs) love