POST /auth/login

POST/auth/login

Authenticate user. Response format depends on accessTokenType configuration: - Header mode (default): Returns tokens in response body - Cookie mode: Sets tokens in HTTP-only cookies and returns success message

Request body

NestAuthLoginRequestDto

Field	Type	Required	Description
`providerName`	`"email" \| "phone" \| "passwordless" \| "google" \| "facebook" \| "apple" \| "github"`	optional	Authentication provider name `emailphonepasswordlessgooglefacebookapplegithub` Default: `"email"` Example: `email`
`credentials`	`object \| object \| object \| object`	required	Login credentials - type varies by provider
`tenantId`	`string`	optional	Tenant ID for multi-tenant applications Example: `123e4567-e89b-12d3-a456-426614174000`
`guard`	`string`	optional	Guard context (e.g. admin, web, vendor) for isolation. Deprecated: use client Example: `admin` deprecated
`createUserIfNotExists`	`boolean`	optional	Auto-create user if not exists (for social auth) Default: `false`

Examples

Email + password

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Phone + password

{
  "phone": "+1234567890",
  "password": "SecurePass123!"
}

Passwordless OTP — set providerName to passwordless (after POST /auth/passwordless/send)

{
  "providerName": "passwordless",
  "credentials": {
    "identifier": "user@example.com",
    "channels": [
      "email",
      "sms"
    ],
    "code": "123456"
  }
}

Social Login (Google/Facebook/etc)

{
  "token": "ya29.a0AfH6SMBx...",
  "type": "idToken"
}

Responses

200Header mode: Returns message + tokens in body

AuthWithTokensResponseDto

Field	Type	Required	Description
`accessToken`	`string`	required	JWT access token (short-lived) Example: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5…`
`refreshToken`	`string`	required	JWT refresh token (long-lived) Example: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVz…`
`message`	`string`	optional	Success message (added by controller based on configuration) Example: `Login successful`
`isRequiresMfa`	`boolean`	required	Whether multi-factor authentication is required Example: `false`
`mfaMethods`	`"email" \| "sms" \| "totp"[]`	optional	Available MFA methods when isRequiresMfa is true Example: `["email","totp"]`
`defaultMfaMethod`	`"email" \| "sms" \| "totp"`	optional	Default/recommended MFA method `emailsmstotp` Example: `email`
`trustToken`	`string`	optional	Trust token for trusted device verification Example: `1234567890`

Example response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5OTksImV4cCI6MTY5OTk5OTk5OX0.xyz",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTY5OTk5OTk5OX0.abc",
  "message": "Login successful",
  "isRequiresMfa": false,
  "mfaMethods": [
    "email",
    "totp"
  ],
  "defaultMfaMethod": "email",
  "trustToken": "1234567890"
}

Try it

curl -X POST 'https://api.example.com/auth/login' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{"providerName":"email","credentials":{"email":"user@example.com","password":"SecurePass123!"},"tenantId":"123e4567-e89b-12d3-a456-426614174000","guard":"admin","createUserIfNotExists":false}'

Login

Request body

Responses

Try it

On this page