API-tokenek és csatlakoztatott appok
A két mód, ahogyan egy nem emberi szereplő elérhet egy boltot; mire képesek, hogyan hozhatsz létre és kezelhetsz API-tokent, és hogyan működnek a korlátai.
Ezen az oldalon
Egy szkript vagy egy AI-eszköz kétféleképpen érhet el egy boltot: API-token segítségével, vagy egy ember által jóváhagyott appként, illetve ügynökként. A választás határozza meg, hogy egy törlés vagy visszatérítés azonnal lefut, vagy emberi jóváhagyásra vár.
| API-token | Csatlakoztatott app vagy ügynök | |
|---|---|---|
| Példák | Egy szkript, egy ERP-szinkronizáció, CI, a poltura egy pipeline-ban | Claude, ChatGPT, Cursor, VS Code, Codex; a Poltura saját asszisztense |
| Létrehozója | Egy ember a Poltura ID felületén vagy a poltura token paranccsal | Egy ember, aki jóváhagyja a bejelentkezést a hozzájárulási oldalon |
| Titkos kulcs | Egy pltu_, plto_ vagy pltd_ token, amely csak egyszer jelenik meg | Nem kell kezelned; a kliens egy automatikusan frissülő OAuth sessiont tart fenn |
| Írási műveletek | Közvetlenül a bolt admin API-ján keresztül és az /mcp műveletein át | Kizárólag műveleteken keresztül: run_action, run_destructive_action és a tipizált műveleti eszközök |
| Törlések és visszatérítések | Azonnal lefutnak az admin API-n | Mindig emberi jóváhagyásra várnak |
| Korlátok | Jogosultságok, boltok, lejárat, IP-szűrő és pontkeret | Ugyanezek, kiegészítve a jóváhagyással, a boltonkénti kapcsolóval és a napi limitekkel |
A poltura login bejelentkezés a tokenek közé tartozik: a CLI a Poltura saját kliense, és a bejelentkezett
személy nevében jár el, akárcsak egy token. Lásd: a CLI.
Egy tokennek csak azokat a jogosultságokat add meg, amelyekre a feladatához feltétlenül szüksége van; OAuth-kapcsolatot akkor használj, ha a törléseket és visszatérítéseket embernek kell jóváhagynia. A jóváhagyás működéséről bővebben: Hogyan járnak el az ügynökök a boltodban.
Tokentípusok
| Előtag | Tulajdonos | Felhasználás |
|---|---|---|
pltu_ | Te | Saját szkriptek. A te nevedben jár el: soha nincs több jogosultsága, mint a saját szerepkörödnek. Egy személyes token egyetlen szervezetet ér el. |
plto_ | Egy szervezet | Szerverek közötti integrációk, amelyeknek egy adott személytől függetlenül kell működniük. Csak olyan személy hozhatja létre, aki rendelkezik az access.tokens.manage jogosultsággal. |
pltd_ | Egy fejlesztői szervezet | App release-ek közzététele CI-ből. Lásd: a CLI. |
A token hossza 51 karakter; ne feltételezz fix hosszt, mivel a dokumentációban szereplő maximális hossz 255. Az utolsó hat karakter egy ellenőrző összeg, így az elgépelt vagy csonka token hálózati hívás nélkül is felismerhető.
Token létrehozása
Nyisd meg a Poltura ID felületén a Fiók, API-tokenek menüpontot személyes tokenhez, vagy az adminfelületen a Beállítások, Szervezet, API és hozzáférés menüpontot szervezeti tokenhez.
Add meg a nevet, a jogosultságokat, a boltokat, az IP-szűrőt és a lejáratot (lásd az alábbi táblázatot).
Másold ki a titkos kulcsot. Csak egyszer jelenik meg.
Vagy hozd létre a parancssorból:
poltura token create --name ERP --permissions orders.read,products.write --stores all --expires 90d| Beállítás | Jelentés |
|---|---|
| Név | A token célja. |
| Jogosultságok | Bolti jogosultságok, például orders.read, valamint szervezeti jogosultságok a --org-permissions kapcsolóval. |
| Boltok | all (beleértve a később hozzáadott boltokat is, az egyes boltok kizárására szolgáló --exclude <store id> kapcsolóval) vagy a boltazonosítók listája. |
| IP-szűrő | Engedélyezett címek vagy CIDR-tartományok, vagy nincs megadva. Bárhonnan máshonnan érkező hívásra a válasz: ip_not_allowed. |
| Lejárat | 7d, 30d (az alapértelmezett), 90d, 1y, egy dátum vagy never, amely figyelmeztetést jelenít meg. |
A titkos kulcs csak egyszer jelenik meg, önmagában a standard kimeneten, így a TOKEN=$(poltura token create …)
működik. Egy token létrehozásához, jogosultságainak bővítéséhez, újbóli engedélyezéséhez és rotálásához friss
második hitelesítési tényezőre van szükség; a CLI bekéri a hitelesítő kódodat, vagy elfogadja a --otp <code> kapcsolót.
A tokenek kezeléséhez a Poltura ID-s session ID-d szükséges (--access-token és --id-token, vagy POLTURA_ACCESS_TOKEN és
POLTURA_ID_TOKEN), soha nem egy másik token, így egy token sosem hozhat létre újabb tokeneket.
Bizonyos jogosultságok soha nem adhatók meg tokennek vagy appnak: a csapat kezelése, maga a hozzáférés, csomagok
vagy domainek vásárlása, számlák kiegyenlítése, valamint minden olyan művelet, amelynek használatához második
hitelesítési tényező szükséges. Ha ilyet kérsz, a válasz not_delegable; végezd el az adminfelületen.
Token használata
curl https://api.poltura.com/v1/tokens/verify -H "Authorization: Bearer $POLTURA_TOKEN"A verify endpoint visszaadja a token azonosítóját, állapotát, lejáratát, tulajdonosát és boltjait, és az IP-szűrő nem
vonatkozik rá. Ugyanezt ellenőrzi a poltura token verify parancs is. A tokent Authorization: Bearer … headerként küldd el a
következő helyekre:
- a bolt admin API-jára:
https://api.poltura.com/v1/stores/<store id>/admin/…, ahol minden route-hoz szükséges a tokenhez rendelt megfelelő jogosultság; - a
https://api.poltura.com/mcpcímre, a következő útmutatókban leírtak szerint: Az MCP-szerver hozzáadása és AI-eszköz csatlakoztatása.
Egyetlen boltra korlátozott tokenhez nem kell boltazonosító az /mcp endpointon; a több boltra érvényes
tokeneknél a store_id paramétert kell használni.
Módosítás, rotálás és visszavonás
| Parancs | Funkció |
|---|---|
poltura token list | Listázza a tokeneket és azok legutóbbi használati idejét. |
poltura token edit <id> | Módosítja a nevet, a szabályzatot, az IP-szűrőt vagy a lejáratot. A titkos kulcs változatlan marad. |
poltura token roll <id> --grace 2 | Új titkos kulcsot állít ki. A régi kulcs a türelmi idő alatt – 0 és 24 óra között – továbbra is működik. Kiszivárgás esetén türelmi idő nélkül rotáld: minden korábbi kulcs azonnal érvényét veszti. |
poltura token disable <id>, enable <id> | Letiltja a tokent, amíg újra nem engedélyezed. |
poltura token delete <id> | Véglegesen visszavonja a tokent. |
A kiszivárgottként bejelentett tokent a rendszer azonnal elutasítja, és e-mailt küld a tulajdonosnak. A tulajdonos hét nappal a token lejárata előtt is kap egy e-mailt, kivéve, ha a token élettartama legfeljebb egy hétre szólt. A személyes token működése leáll, ha a tulajdonosa elhagyja a szervezetet; a szervezeti tokené nem.
Korlátok
Minden tokenen keresztüli hívás pontokat von le egy folyamatosan újratöltődő keretből, amelyet a bolt csomagja határoz meg;
az /mcp kapcsolat ezen felül munkamenet-kerettel, valamint a pénzösszegekre, törlésekre és vásárlói üzenetekre vonatkozó
napi limitekkel is rendelkezik. A táblázatok itt találhatók: Hogyan járnak el az ügynökök a boltodban.
A tokenek esetében két dolog tér el:
- A napi limitekbe csak a csatlakoztatott ügynökök által futtatott műveletek számítanak bele. A tokenek közvetlen admin API calljait a pontkeret korlátozza, nem a napi limitek.
- Minden válasz tartalmazza a hívás költségét és a fennmaradó keretet az
X-Poltura-RateLimit-*headerekben. A keretet túllépő hívásra429 rate_limitedválasz érkezikRetry-Afterheaderrel, a 100 pontnál többe kerülő kérésre pedig400 request_too_costly. Egyik sem érte el a boltot, így a várakozási idő után biztonságosan újrapróbálhatók. Mindkettő részletesen szerepel a Hozzáférési hibák oldalon.