/api/auth/two-factor/verify-backup-code

POST

/api/auth/two-factor/verify-backup-code

curl --request POST \
  --url https://example.com/api/auth/two-factor/verify-backup-code \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "disableSession": true, "trustDevice": true }'

Verify a backup code for two-factor authentication

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

code

required

A backup code to verify. Eg: “123456”

string

disableSession

If true, the session cookie will not be set.

boolean

trustDevice

If true, the device will be trusted for 30 days. It’ll be refreshed on every sign in request within this time. Eg: true

boolean

Example^generated

{
  "code": "example",
  "disableSession": true,
  "trustDevice": true
}

Responses

200

Backup code verified successfully

Media typeapplication/json

object

user

required

The authenticated user object with two-factor details

object

id

required

Unique identifier of the user

string

email

User’s email address

string format: email

nullable

emailVerified

Whether the email is verified

boolean

nullable

name

User’s name

string

nullable

image

User’s profile image URL

string format: uri

nullable

twoFactorEnabled

required

Whether two-factor authentication is enabled for the user

boolean

createdAt

required

Timestamp when the user was created

string format: date-time

updatedAt

required

Timestamp when the user was last updated

string format: date-time

session

required

The current session object, included unless disableSession is true

object

token

required

Session token

string

userId

required

ID of the user associated with the session

string

createdAt

required

Timestamp when the session was created

string format: date-time

expiresAt

required

Timestamp when the session expires

string format: date-time

Example^generated

{
  "user": {
    "id": "example",
    "email": "hello@example.com",
    "emailVerified": true,
    "name": "example",
    "image": "https://example.com",
    "twoFactorEnabled": true,
    "createdAt": "2026-04-15T12:00:00Z",
    "updatedAt": "2026-04-15T12:00:00Z"
  },
  "session": {
    "token": "example",
    "userId": "example",
    "createdAt": "2026-04-15T12:00:00Z",
    "expiresAt": "2026-04-15T12:00:00Z"
  }
}

400

Bad Request. Usually due to missing parameters, or invalid parameters.

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

401

Unauthorized. Due to missing or invalid authentication.

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

403

Forbidden. You do not have permission to access this resource or to perform this action.

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

404

Not Found. The requested resource was not found.

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

429

Too Many Requests. You have exceeded the rate limit. Try again later.

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

500

Internal Server Error. This is a problem with the server that you cannot fix.

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}