Complete a two-factor login and get a Sanctum token

Overview

Second step of a login for an account that has two-factor authentication enabled. POST /api/v1/auth/login answers such an account with a challenge_token instead of a token. This endpoint exchanges that challenge, plus either a current authenticator (TOTP) code or one recovery code, for the same Sanctum personal access token a plain login returns.

A challenge lives 5 minutes, can be redeemed once, and is invalidated after 5 wrong codes. In every one of those cases the client starts again from POST /api/v1/auth/login.

Enabling, confirming and disabling two-factor authentication are not available over the API: they stay on the website.

Controller: App\Http\Controllers\Api\V1\Auth\AuthController::twoFactorChallenge()
Route name: api.v1.auth.two-factor-challenge

Authentication

Type: None. Public endpoint. The challenge_token in the body is the only credential, and it is not a bearer token: sent as Authorization: Bearer it answers 401 Invalid token.
Additional middleware: throttle:two-factor-api — 5 requests per minute per challenge and 10 requests per minute per IP address. This budget is separate from the throttle:auth budget shared by register, login, password/forgot and password/reset.

Request

Method: POST
Path: /api/v1/auth/two-factor-challenge
Content-Type: application/json

Body

{
  "challenge_token": "Zx9kQ2mV7bT4nW1cR8yH5pL0dJ3sF6uAeG2tB9vKq4XoM7iNzC5wY1rD8hE3jP6a",
  "code": "123456"
}

Field	Type	Required	Validation	Description
`challenge_token`	`string`	Yes	`required\|string\|max:255`	The `data.challenge_token` returned by `POST /api/v1/auth/login`
`code`	`string`	One of `code` / `recovery_code`	`nullable\|string\|max:16\|required_without:recovery_code\|prohibits:recovery_code`	Current TOTP code from the authenticator app
`recovery_code`	`string`	One of `code` / `recovery_code`	`nullable\|string\|max:64\|required_without:code`	One unused recovery code

Send exactly one of code and recovery_code. Validated by App\Http\Requests\Api\V1\Auth\TwoFactorChallengeRequest.

Example request

Response `200 OK`

{
  "success": true,
  "status": "success",
  "message": "OK",
  "data": {
    "token": "1|raid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 7775999
  }
}

The payload is identical to a successful POST /api/v1/auth/login for an account without two-factor authentication, and is documented there. The token is named with the device_name sent to the login request that issued the challenge (or the label derived from the User-Agent), not with anything sent here.

Errors

`422 Unprocessable Entity` — wrong code

Returned for a wrong TOTP code, a TOTP code that was already accepted inside its validity window, or a recovery code that is unknown or already used. The key is code or recovery_code, matching the field sent. A wrong code counts towards the 5 failures that invalidate the challenge.

{
  "success": false,
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "code": ["The provided two factor authentication code was invalid."]
  }
}

For recovery_code the message is The provided two factor recovery code was invalid.

`422 Unprocessable Entity` — unknown, expired or used challenge

The same response for a challenge that never existed, has expired, was already redeemed, or was invalidated by 5 failures. It does not say which, and it never says whether the account exists.

{
  "success": false,
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "challenge_token": ["The two-factor challenge is invalid or has expired."]
  }
}

`422 Unprocessable Entity` — validation

Missing challenge_token, neither or both of code and recovery_code. For example, with both sent:

{
  "success": false,
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "code": ["The code field prohibits recovery code from being present."]
  }
}

`429 Too Many Requests`

{
  "success": false,
  "status": "error",
  "message": "Too many requests"
}

Retry-After header present. The throttle:two-factor-api limiter allows 5 requests per minute per challenge_token and 10 per minute per IP address, counting successful and failed attempts alike.

Notes

A recovery code works once. Redeeming it replaces it with a newly generated one on the account; the number of recovery codes does not change.

A TOTP code cannot be used twice inside its validity window, even on a different challenge.

The challenge is held server-side and only a hash of the token is stored. It is deleted as soon as it is redeemed.

Nothing about the account is revealed before the second factor is accepted: a wrong password and an unknown email both answer 401 Invalid credentials at login, and a challenge answers the same 422 whatever happened to it.

Source: docs/api/auth/POST_two_factor_challenge.md

Complete a two-factor login and get a Sanctum token

Overview#

Authentication#

Request#

Body#

Example request#

Response 200 OK#

Errors#

422 Unprocessable Entity — wrong code#

422 Unprocessable Entity — unknown, expired or used challenge#

422 Unprocessable Entity — validation#

429 Too Many Requests#

Notes#

Request

Responses

Overview

Authentication

Request

Body

Example request

Response `200 OK`

Errors

`422 Unprocessable Entity` — wrong code

`422 Unprocessable Entity` — unknown, expired or used challenge

`422 Unprocessable Entity` — validation

`429 Too Many Requests`

Notes