# POST /auth/login

[back to auth](README.md) /// [home](../README.md)

Authenticate and get a session token. No auth required (obviously).

## Request Body

```json
{
  "method": "password",
  "username": "admin",
  "password": "secret"
}
```

## Fields

| Field          | Type   | Required      | Notes                                         |
|----------------|--------|---------------|-----------------------------------------------|
| `method`       | string | yes           | `password`, `pin` or `token`                  |
| `username`     | string | password, pin | required for password and pin methods         |
| `password`     | string | password      | only for password method                      |
| `pin`          | string | pin           | only for pin method                           |
| `login_string` | string | token         | only for token method (NFC cards, badges etc) |

## Auth Methods

### password
Standard username + password. No EyePee Restrictions.

### pin
Short numeric PIN for quick auth (like kiosk scenarios). The clients IP **must** be whitelisted in the servers security config or its a 403. This is a hard requirement, there should never be a bypass for this. ever. seriously. (unless you are dumb enough to set whitelisted IP's to 0.0.0.0/0 for whatever reason but then thats your own fault dumbass)

### token
Login string based auth for things like NFC card scans or badge readers. Same deal as PIN, clients IP **must** be whitelisted or its 403.

## Success Response

```json
{
  "success": true,
  "token": "your-session-token-here",
  "user": {
    "id": 1,
    "username": "admin",
    "name": "Full Name",
    "role": "administrators",
    "power": 100
  }
}
```

Store the `token` and send it on all future requests as `Authorization: Bearer <token>`.

The `user` object gives you basic info about whos logged in. `power` is the users power level (1 lowest, 100 highest) which determines what jsonderulo lets them do.

## Error Responses

| Code | When                                                                         |
|------|------------------------------------------------------------------------------|
| 400  | missing required fields for the chosen method                                |
| 401  | wrong password, wrong pin, wrong login_string, user not found, user inactive |
| 403  | IP not whitelisted (pin and token methods only)                              |
| 500  | database error                                                               |

## Concurrent Sessions

Each user should have a max number of concurrent sessions (configurable per power level + a global default). When a user logs in and is already at the limit the **oldest** session should get automatically evicted from json derulos premises!