---
title: "POST /auth/login - Authentication · RUAL Documentation"
description: "POST: Authenticate user with username and password"
canonical: https://docs.rual.nl/cluster/api/authentication/auth-login-post
language: en
---

# POST /auth/login

Authenticate user with username and password

| Key | Type | Example | Description |
| --- | --- | --- | --- |
| **entity** optional | `string` | `1` | Entity identifier (optional) |
| **password** required | `string` | `"••••••••"` |  |
| **request_refresh_token** optional | `boolean` | 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJndWlkIj...' |  |
| **username** required | `string` | `"joe"` |  |

```
{
  "2fa": [
    "totp"
  ],
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJndWlkIjoiYjllZTZhNjMxYjI0In0",
  "default_2fa": "totp",
  "device": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36"
  },
  "expiry": 3600,
  "expiry_renew": 604800,
  "ip": "192.168.1.100",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJndWlkIjoiYjllZTZhNjMxYjI0In0",
  "refresh_token_expiry": 604800,
  "user": {
    "_meta": {
      "created": 1782080295,
      "entity": 1,
      "guid": "b9ee6a631b24e78d1aa48aef0dc067fff7bfbacd24a56ef4ed1f08e537d48b6b",
      "removed": 0,
      "updated": 1782166695
    },
    "email": "joe@example.com",
    "firstname": "Joe",
    "language": "en",
    "lastname": "Doe",
    "username": "joe"
  },
  "verified": true
}
```

```
{
  "code": 401,
  "error": "INVALID_ACCESS_TOKEN"
}
```

| Status | Error Code | Description |
| --- | --- | --- |
| `401` | `INVALID_ACCESS_TOKEN` | Authentication required or invalid token |
| `403` | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions for this operation |
| `429` | `TOO_MANY_LOGIN_ATTEMPTS` | Too many requests - rate limit exceeded |

| Permission | Description |
| --- | --- |
| `*public` | No authentication required, public endpoint |