# Hitelesítés

> API-tokenek, hozzáférési szintek, engedélyezett IP-címek.

## API-tokenek

Minden kérés egy munkaterületi API-tokent visz az `Authorization` fejlécben:

```http
Authorization: Bearer upm_...
```

- Egy token egy munkaterülethez tartozik. Minden, amit olvasol vagy módosítasz, abban a munkaterületben van.
- Tokent az **Integrációk**, **API**, **Új token létrehozása** úton hozhatnak létre az Adminisztrátor és a Menedzser szerepkörű felhasználók. Az értékét az Echo egyszer mutatja meg, és csak egy lenyomatát tárolja.
- A felület tokenlistája mutatja minden token első karaktereit, a hozzáférését, az engedélyezett IP-címeit és azt, hogy mikor használták utoljára.
- Egy munkaterületnek legfeljebb 50 aktív tokenje lehet.
- A tokent csak a saját háttérrendszeredben használd. Az API nem küld CORS-fejléceket, így böngészőből amúgy sem hívható.

Az egyetlen végpont, amelyhez nem kell token, a `GET /openapi.yaml` dokumentum.

## Hozzáférési szintek

A tokennek kétféle hozzáférési szintje lehet. Létrehozáskor kell választani, később nem módosítható:

| Hozzáférés | Mit enged |
|---|---|
| Csak olvasás | Minden `GET` végpontot, amelyet a létrehozó szerepköre megenged. |
| Teljes hozzáférés | Olvasást és írást, amennyire a létrehozó szerepköre megengedi. |

A token mindig a **létrehozója mindenkori szerepkörével** dolgozik: a hozzáférési szint ezt csak szűkítheti. Minden végponthoz egy terület joga kell:

| Végpontok | Olvasáshoz | Íráshoz |
|---|---|---|
| Feliratkozók, csoportok, szegmensek, mezők, importok | Feliratkozók: megtekintés | Feliratkozók: kezelés |
| Kampányok | Kampányok: megtekintés | Kampányok: kezelés |
| Automatizálások | Automatizálások: megtekintés | Automatizálások: kezelés |
| Webhookok | Beállítások: megtekintés | Beállítások: kezelés |
| `GET /timezones`, `POST /batch` | bármely érvényes token | bármely érvényes token |

A beépített Adminisztrátor és Menedzser szerepkörnek a fenti jogok mind megvannak. Jog nélkül a válasz `403 forbidden`:

```json
{"error":{"code":"forbidden","message":"You don't have permission to do this."}}
```

Egyes válaszok tartalma is a jogoktól függ:

- A webhookok URL-jét csak a Beállítások: kezelés joggal bíró token látja teljesen. A többiek csak az eredetet, például `"url":"https://hooks.example.com/…"`.
- A kampánytevékenységben és a munkafolyamatok futásaiban a feliratkozó `email` értékéhez és a `search` paraméterhez Feliratkozók: megtekintés jog kell. Enélkül a sorokban csak a feliratkozó `id` értéke szerepel, a `search` pedig `403` választ ad.

## Engedélyezett IP-címek

Egy token legfeljebb 20 IP-címre vagy tartományra korlátozható (például `203.0.113.7` vagy `203.0.113.0/24`). Más címről érkező kérésre a válasz:

```http
HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":{"code":"ip_not_allowed","message":"This API token can't be used from your IP address."}}
```

## Mikor áll le egy token

Az Echo minden kérésnél ellenőrzi a tokent, így ezek azonnal érvényesek:

| Változás | Válasz |
|---|---|
| A tokent visszavonták | `401 unauthenticated` |
| A létrehozót eltávolították a munkaterületről, vagy letiltották a felhasználóját | `401 unauthenticated` (a felület **Inaktív** jelzést mutat) |
| A létrehozó szerepköre megváltozik | A következő kéréstől az új szerepkör érvényes |
| A munkaterületet felfüggesztették | `403 workspace_suspended` |
| A munkaterület kétlépcsős azonosítást követel, és a létrehozó nem állította be | `403 twofa_enforced` (amint beállítja, a token újra működik) |

A tokennel végzett változások a munkaterület tevékenységnaplójába a token nevével kerülnek.

## Hitelesítési hibák

Hiányzó, hibás, ismeretlen vagy visszavont token:

```bash
curl -i "$ECHO_API/subscribers"
```

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Www-Authenticate: Bearer realm="upmail"

{"error":{"code":"unauthenticated","message":"Missing, unknown or revoked API token."}}
```

A sikertelen hitelesítés nem számít bele a sebességkorlátba, és a válaszában nincsenek `X-RateLimit-*` fejlécek.