Authenticate with a recovery code

Verifies the second factor of the session started by POST /api/v1/auth.

post

Authorizations

cookieapi_token

defguard_sessionstringRequired

Body

application/json

codestringRequired

Responses

200

Recovery code verified, user is fully authenticated.

application/json

Return type needed for knowing if a user came from OpenID flow. If so, fill in the optional URL field to redirect him later.

urlstring · nullableOptional

401

Session is missing or invalid.

application/json

500

Unable to verify recovery code.

application/json

post/api/v1/auth/recovery

HTTPcURLJavaScriptPython

POST /api/v1/auth/recovery HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "code": "text"
}

{
  "url": null,
  "user": {
    "authorized_apps": [
      {
        "oauth2client_id": 1,
        "oauth2client_name": "text"
      }
    ],
    "devices": [
      {
        "configured": true,
        "created": "2026-08-07T20:38:36.165Z",
        "description": null,
        "device_type": "user",
        "id": 1,
        "name": "text",
        "user_id": 1,
        "wireguard_pubkey": "text",
        "networks": [
          {
            "device_wireguard_ips": [
              "text"
            ],
            "is_active": true,
            "last_connected_at": null,
            "last_connected_ip": null,
            "location_mfa_mode": "disabled",
            "network_gateway_ip": "text",
            "network_id": 1,
            "network_name": "text"
          }
        ]
      }
    ],
    "email": "text",
    "email_mfa_enabled": true,
    "enrolled": true,
    "first_name": "text",
    "groups": [
      "text"
    ],
    "id": 1,
    "is_active": true,
    "is_admin": true,
    "last_name": "text",
    "ldap_pass_requires_change": true,
    "mfa_enabled": true,
    "mfa_method": "None",
    "name": "text",
    "phone": null,
    "totp_enabled": true,
    "username": "text"
  }
}