# Autenticación

> Login por sesión y modelo de permisos

<Warning>
**Para probar en el playground: primero ejecutá `POST /v1/login` (botón *Pruébalo*).**
La sesión es por cookie, así que queda guardada en tu navegador y el resto de los
endpoints la reusan. Si probás cualquier otro endpoint sin loguearte antes, la
respuesta es `UNAUTHORIZED` - "Debe iniciar sesión". Usá el usuario de tu propia
empresa, el mismo con el que entrás a pymo.
</Warning>

## Login

```bash
curl -c cookies.txt -X POST {base}/v1/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "empresa@ejemplo.com", "password": "********" }'
```

Respuesta:

```json
{ "payload": { "email": "empresa@ejemplo.com" },
  "message": { "code": "LOGGED_IN", "value": "Sessión iniciada correctamente." },
  "status": "SUCCESS" }
```

La sesión se mantiene por **cookie**: enviar la cookie devuelta en cada request
siguiente (`-b cookies.txt` en curl).

Cada sucursal (branch office) tiene su propia cuenta `email + password`, creada
por pymo durante el onboarding de la empresa.

## Permisos

La sesión queda atada al RUT de la empresa: sólo puede operar sobre
`/v1/companies/{suRut}/...` y los recursos de referencia (`/v1/currenciesQuotes`,
`/v1/dgiData/{suRut}`). Cualquier otro path devuelve `403 FORBIDDEN`.

### Clasificación de acceso

Cada endpoint de la referencia dice a qué categoría pertenece, en la línea
**Acceso** de su descripción:

| Categoría | Qué significa | Cuántos |
|---|---|---|
| Pública | No requiere sesión | 2 |
| Restringida | Requiere sesión; no está atada a un RUT (datos de referencia y `logout`) | 5 |
| Restringida por RUT | Requiere sesión y opera sólo sobre tu propia empresa | 54 |

Las otras dos categorías que se podrían esperar están vacías, y conviene decirlo:

- **Interna / de administración**: existe en el gateway, pero no se publica acá.
  Ninguno de esos endpoints aparece en esta referencia.
- **Obsoleta**: ninguno. Nada de lo documentado está anunciado para
  desaparecer.

Respuesta sin sesión o sin permiso (`HTTP 401`):

```json
{
  "payload": {},
  "message": { "code": "UNAUTHORIZED", "value": "Debe iniciar sesión." },
  "status": "FAIL"
}
```

## Logout

```bash
curl -b cookies.txt -X POST {base}/v1/logout
```

Respuesta (`HTTP 200`):

```json
{ "payload": {},
  "message": { "code": "LOGGED_OUT", "value": "Sessión cerrada correctamente" },
  "status": "SUCCESS" }
```

## Cuánto dura la sesión

**Una hora desde el login**, y es un vencimiento absoluto: usar la API no lo
extiende. Es la misma hora en homologación y en producción.

Cuando vence, cualquier endpoint responde `401` con `UNAUTHORIZED` igual que si
nunca hubieras iniciado sesión. No hay refresh: se vuelve a llamar a
`POST /v1/login`.

La sesión sobrevive a un reinicio del servicio: si tu llamada falla con un
error de red y reintentás, la sesión sigue viva. Lo que la termina es el
vencimiento o `POST /v1/logout`.