> 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/for-developers/rest-api/core/auth/authenticate-a-user.md).

# Authenticate a user

```json
{"openapi":"3.1.0","info":{"title":"defguard Core API","version":"2.0.3"},"tags":[{"name":"auth","description":"User authentication, second authentication factor and session management."}],"paths":{"/api/v1/auth":{"post":{"tags":["auth"],"summary":"Authenticate a user","operationId":"authenticate","requestBody":{"description":"`username` also accepts the user's email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auth"}}},"required":true},"responses":{"200":{"description":"User authenticated.","headers":{"Set-Cookie":{"schema":{"type":"string"},"description":"`defguard_session` cookie."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"201":{"description":"A second authentication factor is required. Verify one of the listed methods with the matching `/api/v1/auth/{method}` endpoint.","headers":{"Set-Cookie":{"schema":{"type":"string"},"description":"`defguard_session` cookie of a not fully authenticated session."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MFAInfo"}}}},"401":{"description":"Invalid credentials or user groups are not synced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"License user limit reached.","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 authenticate user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}},"components":{"schemas":{"Auth":{"type":"object","required":["username","password"],"properties":{"password":{"type":"string"},"username":{"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","devices"],"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"}},"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"},"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"]},"MFAInfo":{"type":"object","required":["mfa_method","totp_available","webauthn_available","email_available"],"properties":{"email_available":{"type":"boolean"},"mfa_method":{"$ref":"#/components/schemas/MFAMethod"},"totp_available":{"type":"boolean"},"webauthn_available":{"type":"boolean"}}},"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."}}}}}}
```