Authentication

Login

Authenticate a user and return JWT tokens.

Validates the user’s credentials against the specified account and returns JWT tokens for authenticated access.

Flow:

Resolve account by slug or ID
Look up user by email in account
Check authentication provider (OAuth/SAML users must use their respective flows)
Verify password using timing-safe comparison
Check if user is active
Update last_login timestamp
Generate JWT tokens
Return response

Security:

All authentication failures return the same generic 401 message
Password verification is always performed (even with dummy hash) to prevent timing attacks

POST

api

auth

curl --request POST \
  --url https://api.example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "password": "<string>",
  "account": "<string>"
}
'

{
  "token": "<string>",
  "refresh_token": "<string>",
  "expires_in": 123,
  "account": {
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "user": {
    "id": "<string>",
    "email": "<string>",
    "role": "<string>",
    "is_active": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
}

Body

application/json

Request body for user login.

string<email>

required

User's email address

password

string

required

User's password

Minimum string length: 1

account

string | null

Account identifier (slug or ID in XX#### format). Required in multi-tenant mode.

Minimum string length: 1

Response

Successful Response

Response for successful authentication (login).

token

string

required

JWT access token

refresh_token

string

required

JWT refresh token

expires_in

integer

required

Access token expiration time in seconds

account

AccountResponse · object

required

Account information

Show child attributes

user

UserResponse · object

required

User information

Show child attributes

Refresh TokensRefresh access and refresh tokens. Validates the provided refresh token, issues new tokens, and invalidates the old refresh token (token rotation). Flow: 1. Validate refresh token (signature, expiration, type) 2. Check if token is revoked in database 3. Get user information from token claims 4. Revoke old refresh token 5. Generate new access token and refresh token 6. Store new refresh token 7. Return new tokens

curl --request POST \
  --url https://api.example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "password": "<string>",
  "account": "<string>"
}
'

{
  "token": "<string>",
  "refresh_token": "<string>",
  "expires_in": 123,
  "account": {
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "user": {
    "id": "<string>",
    "email": "<string>",
    "role": "<string>",
    "is_active": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
}