API-kulcsok és hitelesítés

Minden REST-hívást és minden MCP-munkamenetet egy API-kulcs hitelesít, amelyet az alkalmazásban hozol létre. A kulcs a nevedben jár el, de csak azokkal a jogosultságokkal, amelyeket megadsz neki. Egyféle kulcs és egyetlen header létezik, a REST API-hoz és az MCP-szerverhez egyaránt.

app.stickyprompts.com/settings#api 1 Kulcs létrehozása 2 Csak erre a headerre van szükség 3 Átnevezés, jogosultságok, törlés

Kulcs létrehozása

1. Nyisd meg a Settings > API keys oldalt

   Lépj a Settings oldalra, és válaszd az API keys menüpontot.

2. Generálj egy kulcsot

   Kattints a Generate key gombra. Adj a kulcsnak olyan nevet, amelyből kiderül, hol fogod használni (például Northwind CRM sync), és jelöld be a szükséges jogosultságokat - ezekről a Jogosultságok referenciája oldalon olvashatsz.

3. Másold ki a kulcsot

   A teljes kulcs csak egyszer jelenik meg, közvetlenül a létrehozás után. Később sem te, sem a StickyPrompts nem tudja előhívni. Tedd el azonnal a titokkezelődbe (secret manager).

Kulcsot csak az alkalmazásba bejelentkezett felhasználó hozhat létre. A kulcskezelő végpontok API-kulccsal nem hívhatók, így egy kulcs soha nem hozhat létre, listázhat vagy módosíthat kulcsokat.

A kulcs formátuma

STICKY-API-<64 characters>

• Az előtag mindig STICKY-API-, ezt 64 véletlenszerű karakter követi. A teljes kulcs 75 karakter hosszú.
• A véletlenszerű rész számjegyekből, mássalhangzókból (magánhangzó nincs benne), valamint - és _ karakterekből áll.
• A StickyPrompts csak a titok hash-ét tárolja, valamint az első 16 karakterét, hogy megtalálja a kulcsot. Ezért egy elveszett kulcsot nem lehet újra megjeleníteni.

Életciklus

A kulcs elküldése

A kulcsot minden kérésben Bearer-tokenként, az Authorization headerben küldd el:

Authorization: Bearer STICKY-API-...

A Bearer STICKY-API- előtagban számít a kis- és nagybetű, és pontosan így kell szerepelnie. Query stringben vagy cookie-ban nem küldheted el a kulcsot.

curl https://api.stickyprompts.com/api/v1/workspace \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os
import requests

r = requests.get(
    "https://api.stickyprompts.com/api/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
)
print(r.status_code, r.json())

const res = await fetch("https://api.stickyprompts.com/api/v1/workspace", {
  headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` },
});
console.log(res.status, await res.json());

(A GET /workspace hívásához az organization_get jogosultság kell.)

Mit lát egy kulcs?

A kulcs annak a felhasználónak a nevében jár el, aki létrehozta. Pontosan azt látja, amit ő: a munkaterületét, a projektjeit és mindent, amit megosztottak vele. A kulcs jogosultságai ezt tovább szűkítik. Kulcsot nem lehet egy adott munkaterületre vagy projektre korlátozni.

Ha a fiókod már nem aktív, a kulcsaid sem működnek tovább. Ha kilépsz egy munkaterületről, vagy elveszíted a hozzáférést egy projekthez, a kulcsaid is elveszítik ezt a hozzáférést.

Így ellenőrzi a rendszer a kéréseket

Minden kérés végigmegy az alábbi ellenőrzéseken, ebben a sorrendben. Az első sikertelen ellenőrzés határozza meg a választ.

Ettől függetlenül a rendszer 403 {"error":"access from your region is not supported"} válasszal utasítja el azokat a kéréseket, amelyek olyan régióból érkeznek, amelyet a szolgáltatás nem szolgál ki. Ez a REST-re és az MCP-re egyaránt vonatkozik.

A jogosultsági hiba megnevezi a hiányzó jogosultságot, így a megoldás általában annyi, hogy szerkeszted a kulcsot, és bejelölöd:

{"error": "This api key does not have any of the required permissions. You need at least one of: prompts_get"}

MCP-n a 4. lépés másként működik: bármely érvényes, aktív kulcs csatlakozhat, azok az eszközök pedig, amelyekhez a kulcsnak nincs jogosultsága, egyszerűen nem jelennek meg. Részletek: Az MCP áttekintése.

Végpontok, amelyeket kulccsal soha nem érhetsz el

Az API egyes részei az alkalmazásba bejelentkezett felhasználónak vannak fenntartva. Ezeken egy API-kulcs mindig 403-as választ kap, bármilyen jogosultsága van:

• Fiók-, bejelentkezési és hitelesítési végpontok.
• Számlázási és előfizetési végpontok.
• Az API-kulcsok kezelése (kulcsok létrehozása, listázása, szerkesztése és törlése).
• A StickyPrompts munkatársainak adminisztrációs végpontjai.
• Néhány végpont, amelyhez nincs API-kulcs-jogosultság rendelve, például egyetlen prompt lekérése (GET /prompt/:id) és az ügynökök megosztása (GET /agents/:id/shares és a PATCH /agents/:id/share_with_* végpontok). Ügynököt az alkalmazásban tudsz megosztani.

A kulcsok biztonsága

• Csak szerveroldalon. A kulcsokat környezeti változókban vagy titokkezelőben tárold. Soha ne commitold és ne naplózd őket, és ne másold be őket ticketekbe vagy chatekbe.
• A legkisebb jogosultság elve. Csak azokat a jogosultságokat jelöld be, amelyeket az integráció ténylegesen használ. Egy riportkészítő botnak nincs szüksége az integration_email_manage jogosultságra. Indulj ki a javasolt jogosultságcsomagokból.
• Integrációnként egy kulcs. Minden kulcsot arról a rendszerről nevezz el, amely használja. Így egy integráció kulcsát a többi érintése nélkül vonhatod vissza, és az utolsó használat időpontjából azt is látod, hogy aktív-e még.
• Rendszeres csere. Cseréld a kulcsokat a neked megfelelő ütemezés szerint, és azonnal, ha távozik valaki, aki hozzáfért, vagy ha egy kulcs kiszivároghatott. Előbb hozd létre az újat, állj át rá, és csak utána töröld a régit.
• Ne feledd, kinek a nevében jár el a kulcs. A kulcs a te nevedben jár el. Közös integrációhoz érdemes olyan fiókból létrehozni a kulcsot, amelynek a hozzáférése pontosan annak felel meg, amit az integrációnak látnia kell.

Kapcsolódó oldalak