Hitelesítés

API-tokenek

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

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:

{"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/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:

curl -i "$ECHO_API/subscribers"

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.