API-kulcsok és hatókörök

A Sursa API-hoz küldött minden kérés a szervezeted egyik API-kulcsával történik. A kulcs a szervezethez tartozik, nem egy személyhez: akkor is tovább működik, ha a létrehozó munkatárs távozik, és hogy mire képes, azt magán a kulcson állítod be.

Mit tehet egy kulcs

A kulcs három beállítása dönti el, mit láthat és mit módosíthat a vele küldött kérés. Mindegyik csak szűkíti a többit.

Beállítás	Mit szabályoz
Role (szerepkör)	`admin`, `editor`, `verifier` vagy `viewer`, ugyanazok a szerepkörök, mint a felhasználóknál. A kulcs azt teheti, amit egy ilyen szerepkörű felhasználó.
Scopes (hatókörök)	Az API mely részeit hívhatja a kulcs, például `cards:read` vagy `webhooks:manage`. Lásd: A kulcsok hatókörei.
Data profile (adatprofil)	Nem kötelező. A kulcsot a tudásnak azokra a kategóriáira korlátozza, amelyeket a profil megenged, mint egy ilyen profilú felhasználót.

Egy kulcs bizonyos gyűjteményekre is korlátozható, és lejárati dátumot is kaphat. A korlátokon kívül eső kérés meghiúsul: hiányzó hatókör esetén a válasz 403 az api_keys.scope kóddal, a kulcs számára nem látható objektumra pedig 404, pontosan úgy, mintha nem is létezne.

Minden integrációnak adj saját kulcsot, a szükséges legszűkebb szerepkörrel és hatókörökkel. Egy csak dokumentumokat író szinkronizálási feladatnak nincs szüksége admin szerepkörre; egy jelentéskészítő feladatnak nincs szüksége írási hatókörökre.

Kulcs létrehozása

A kulcsokat a szervezet adminisztrátora hozza létre a Sursában, az Administration → API keys (adminisztráció → API-kulcsok) alatt, vagy a POST /v1/api-keys végponttal, admin szerepkörű kulccsal vagy munkamenettel:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

A válasz a key mezőben tartalmazza a kulcs értékét. Ez egyszer jelenik meg: a Sursa csak a hash-ét tárolja, és nem tudja újra megmutatni. A kulcs kb_ előtagból és 43 további karakterből áll; az első karakterei (prefix) megjelennek a kulcsok listájában, így meg tudod különböztetni a kulcsokat.

scopes nélkül a kulcs a szerepköre hatóköreit kapja. A további szűkítéshez add meg a scopes mezőt. expires_at nélkül a kulcs nem jár le.

A kulcsok titokban tartása

A kulcsokat titokkezelőben vagy a szolgáltatásod környezeti változóiban tárold, soha ne a forráskódban.
A kulcsokat csak a saját szervereidről használd. A Sursa böngészőből érkező kéréseket is fogad (a CORS nyitott), de a weboldalon elhelyezett kulcsot mindenki látja, aki megnyitja az oldalt.
Soha ne küldd a kulcsot URL-ben. Csak az Authorization fejlécben küldd.
Ha egy kulcs kiszivárog, azonnal vond vissza, és hozz létre újat.

Kulcs ellenőrzése

A GET /v1/me visszaadja a kulcsot, a szerepkörét, a tényleges hatóköreit, az adatprofilját, a lejáratát és a gyakorisági korlátját. Bármely érvényes kulccsal működik, bármilyenek is a hatókörei, ezért használd az integrációd kapcsolattesztjeként, és akkor is, amikor egy 403 válasz okát keresed.

Kulcs megújítása

A megújítás az integráció leállítása nélkül cseréli le a kulcsot. A leggyorsabb mód a kulcs értékének megújítása: a POST /v1/api-keys/{key_id}/roll új értéket ad ki ugyanahhoz a kulcshoz, ugyanazzal a szerepkörrel, hatókörökkel, gyűjteményekkel és lejárattal. Az előző érték overlap_hours óráig (alapértelmezés szerint 24, legfeljebb 168 óráig) tovább működik, így közben telepítheted az új értéket; a POST /v1/api-keys/{key_id}/revoke-previous korábban lezárja az átfedési időt.

Ha inkább egy másik kulcsra cserélnéd a kulcsot:

Hozz létre egy új kulcsot ugyanazzal a szerepkörrel, hatókörökkel és adatprofillal.
Állítsd be az új kulcsot az integrációdban.
Figyeld a régi kulcsot az Administration → API keys alatt (vagy a GET /v1/api-keys válaszában a last_used mezőt), amíg már nem használják.
Vond vissza a régi kulcsot.

Állíts be lejárati dátumot a kulcsokon, és újítsd meg őket előtte. A Sursa a lejárat előtt figyelmezteti a szervezet adminisztrátorait; a lejárt kulcsra a válasz 401 az api_keys.expired kóddal.

Kulcs visszavonása

A kulcsot az Administration → API keys alatt vagy a DELETE /v1/api-keys/{key_id} végponttal vonhatod vissza. A visszavonás másodperceken belül érvénybe lép minden API-szerveren. A visszavont kulccsal küldött kérésekre a válasz 401 az auth.not_authenticated kóddal.

Az egyéni források kulcsai

Az egyéni forrásnak saját kulcsfajtája van. kbsrc_ előtaggal kezdődik, csak abba az egy forrásba írhat dokumentumokat, és semmit nem olvashat és nem kereshet. Ez a legbiztonságosabb kulcs, amelyet egy integrációs platformnak, például a Zapiernek átadhatsz. A forrás oldalán, az API keys szakaszban hozhatod létre, vagy a POST /v1/sources/{source_id}/push-keys végponttal.

Ha nem érhetők el kulcsok

Az API-kulcsok a szervezet csomagjának részei. Ha a csomag nem tartalmazza őket, a kulcs létrehozására és minden kulccsal küldött kérésre a válasz 403 az api_keys.feature_disabled kóddal.