> For the complete documentation index, see [llms.txt](https://docs.defguard.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.defguard.net/2.1/for-developers/rest-api/core/auth/verify-a-totp-code.md).

# Verify a TOTP code

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

```json
{"openapi":"3.1.0","info":{"title":"defguard Core API","version":"2.1.0"},"tags":[{"name":"auth","description":"User authentication, second authentication factor and session management."}],"security":[{"cookie":[]},{"api_token":[]}],"components":{"securitySchemes":{"cookie":{"type":"apiKey","in":"cookie","name":"defguard_session"},"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"AuthCode":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}},"AuthResponse":{"type":"object","description":"Return type needed for knowing if a user came from OpenID flow.\nIf so, fill in the optional URL field to redirect him later.","required":["user"],"properties":{"url":{"type":["string","null"]},"user":{"$ref":"#/components/schemas/UserInfo"}}},"UserInfo":{"type":"object","required":["id","username","last_name","first_name","name","email","mfa_enabled","totp_enabled","email_mfa_enabled","groups","mfa_method","authorized_apps","is_active","enrolled","is_admin","ldap_pass_requires_change","password_management_disabled","devices","has_non_mfa_location_access","has_non_posture_location_access"],"properties":{"authorized_apps":{"type":"array","items":{"$ref":"#/components/schemas/OAuth2AuthorizedAppInfo"}},"devices":{"type":"array","items":{"$ref":"#/components/schemas/UserDevice"}},"email":{"type":"string"},"email_mfa_enabled":{"type":"boolean"},"enrolled":{"type":"boolean"},"first_name":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"has_non_mfa_location_access":{"type":"boolean"},"has_non_posture_location_access":{"type":"boolean"},"id":{"$ref":"#/components/schemas/i64"},"is_active":{"type":"boolean"},"is_admin":{"type":"boolean"},"last_name":{"type":"string"},"ldap_pass_requires_change":{"type":"boolean"},"mfa_enabled":{"type":"boolean"},"mfa_method":{"$ref":"#/components/schemas/MFAMethod"},"name":{"type":"string"},"password_management_disabled":{"type":"boolean"},"phone":{"type":["string","null"]},"totp_enabled":{"type":"boolean"},"username":{"type":"string"}}},"OAuth2AuthorizedAppInfo":{"type":"object","required":["oauth2client_id","oauth2client_name"],"properties":{"oauth2client_id":{"$ref":"#/components/schemas/i64"},"oauth2client_name":{"type":"string"}}},"i64":{"type":"integer","format":"int64"},"UserDevice":{"allOf":[{"$ref":"#/components/schemas/Device_i64"},{"type":"object","required":["networks"],"properties":{"networks":{"type":"array","items":{"$ref":"#/components/schemas/UserDeviceNetworkInfo"}}}}]},"Device_i64":{"type":"object","required":["id","name","wireguard_pubkey","user_id","created","device_type","configured"],"properties":{"configured":{"type":"boolean","description":"Whether the device is ready to use. Unconfigured devices are not sent to the gateway.\nSuch a device is already added to all its networks, but is still missing something,\nfor example its public key."},"created":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"device_type":{"$ref":"#/components/schemas/DeviceType"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"user_id":{"$ref":"#/components/schemas/i64"},"wireguard_pubkey":{"type":"string"}}},"DeviceType":{"type":"string","enum":["user","network"]},"UserDeviceNetworkInfo":{"type":"object","required":["network_id","network_name","network_gateway_ip","device_wireguard_ips","is_active","location_mfa_mode"],"properties":{"device_wireguard_ips":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_connected_at":{"type":["string","null"],"format":"date-time"},"last_connected_ip":{"type":["string","null"]},"location_mfa_mode":{"$ref":"#/components/schemas/LocationMfaMode"},"network_gateway_ip":{"type":"string"},"network_id":{"$ref":"#/components/schemas/i64"},"network_name":{"type":"string"}}},"LocationMfaMode":{"type":"string","enum":["disabled","internal","external"]},"MFAMethod":{"type":"string","enum":["None","OneTimePassword","Webauthn","Email"]},"ApiErrorResponse":{"type":"object","description":"Body returned with error responses.","required":["msg"],"properties":{"code":{"type":["string","null"],"description":"Machine-readable error code, returned for selected errors."},"msg":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/auth/totp/verify":{"post":{"tags":["auth"],"summary":"Verify a TOTP code","description":"Verifies the second factor of the session started by `POST /api/v1/auth`.","operationId":"totp_code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthCode"}}},"required":true},"responses":{"200":{"description":"TOTP code verified, user is fully authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Session is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"User not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"Too many failed login attempts for this user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Unable to verify TOTP code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```