Každý požadavek na API se autentizuje API klíčem. Klíč patří uživateli, který ho vytvořil: požadavky s ním se provádějí jménem tohoto uživatele, vidí to, co vidí on, a čerpají jeho kredity (nebo kredity jeho organizace).
API klíče
Klíče vytvoříte v aplikaci AYETO v sekci Profil → API klíče:
- Zvolte nový, pojmenujte klíč (a volitelně přidejte popis).
- Vyberte rozsahy, které klíč potřebuje.
- Zkopírujte klíč z potvrzovacího dialogu. Celý klíč se zobrazí jen jednou; poté aplikace ukazuje jen jeho začátek a konec, abyste ho poznali.
Klíč vypadá takto:
ayeto-1f0c2b7e9a4d4c6f8e3b5a7d9c1e2f40a8b6c4d2e0f1a3b5c7d9e1f2a4b6c8d0
Platnost klíčů nevyprší. Klíč zneplatníte tak, že ho na stejném místě smažete; požadavky se smazaným klíčem okamžitě selžou.
Zacházejte s klíčem jako s heslem: držte ho na svém serveru nebo v úložišti tajných údajů, nikdy ve správě verzí ani v kódu, který běží v cizím prohlížeči.
Posílání klíče
Klíč posílejte v hlavičce uni-api-key každého požadavku:
curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit_from": 0, "limit_to": 5}'
Endpointy v této dokumentaci žádnou jinou autentizaci (cookies, bearer tokeny) nepotřebují ani nepřijímají.
Rozsahy
Rozsah (scope) povoluje klíči volat skupinu endpointů. Dejte každému klíči jen ty
rozsahy, které potřebuje. Klíč se všemi rozsahy (*) může volat každý endpoint.
| Rozsah | V aplikaci zobrazen jako | Povoluje |
|---|---|---|
* |
Všechny rozsahy | Každý endpoint, včetně těch, které vyžadují rozsah neuvedený níže. |
ayeto.chat |
AYETO chat | Chat |
ayeto.conversation |
AYETO konverzace | Konverzace |
ayeto.assistant |
AYETO asistenti | Výpis asistentů a jejich avatarů |
ayeto.workflow |
AYETO workflow (čtení a spouštění) | Čtení a spouštění workflow, běhy, schválení |
ayeto.workflow.write |
AYETO workflow (úpravy) | Vytváření, úpravy, publikování, import a mazání workflow |
ayeto.booster.database |
AYETO booster databáze (čtení) | Čtení záznamů booster databáze |
ayeto.booster.database.write |
AYETO booster databáze (zápis) | Vytváření, úpravy a mazání záznamů, zámky |
ayeto.booster.storage |
AYETO booster úložiště souborů (čtení) | Výpis souborů booster panelu, odkazy ke stažení |
ayeto.booster.storage.write |
AYETO booster úložiště souborů (zápis) | Nahrávání, přesouvání a mazání souborů panelu |
ayeto.tts |
AYETO převod textu na řeč | Převod textu na řeč |
ayeto.data_loader |
AYETO text ze souboru | Převod souboru na text |
ayeto.embeddings |
AYETO embeddings | Embeddings |
Endpoint, který vyžaduje několik rozsahů, potřebuje na klíči všechny. Endpointy, které mají jako rozsah uvedeno „jakýkoli API klíč“, přijmou každý platný klíč. Souhrnná tabulka každého endpointu uvádí rozsah, který vyžaduje.
Aplikace nabízí také rozsah AYETO konektory (ayeto.connector). Používají ho
desktopoví klienti AYETO při spárování s vaším účtem a pro toto API ho nepotřebujete.
Klíč vytvořený spárováním desktopového klienta má jen tento rozsah a endpointy výše
volat nemůže.
Booster panely jednající za přihlášeného člověka
Booster panel s uživatelskými účty může lidem dovolit přihlášení účtem AYETO. Když to vlastník panelu povolí, může pak panel volat toto API jako daný člověk: přihlašovací obrazovka ukáže, o co panel žádá (rozsahy z tabulky výše, nebo všechny), a člověk s tím přihlášením souhlasí.
- Panel posílá token relace, který dostal při přihlášení (začíná
bpu_), v hlavičceuni-api-key, stejně jako API klíč. Žádná další hlavička není potřeba. - Požadavek běží jako účet daného člověka s odsouhlasenými rozsahy, nikdy ne s více, než o kolik panel právě žádá. Každý endpoint používá organizace, asistenty a workflow, ke kterým má účet přístup, jako s vlastním API klíčem účtu, a čerpá kredity účtu.
- Endpointy, které přijímají libovolný API klíč, přijímají i takový token.
- Odhlášení z panelu, ukončení relace, ztráta práva přihlásit se do panelu (např. odchod z jeho
organizace) nebo užší nastavení panelu ukončí přístup do minuty; token se pak odmítá jako
neplatný klíč (
401). - Relace účtů panelu přihlášených heslem nebo kódem z e-mailu přístup k API nikdy nedostanou.
Chyby autentizace
| Stav | detail |
Příčina |
|---|---|---|
422 |
chyba validace požadavku jmenující uni-api-key |
Chybí hlavička uni-api-key. |
401 |
API key not provided |
Hlavička uni-api-key je prázdná. |
401 |
API key is invalid |
Klíč neexistuje, byl smazán nebo vypnut, nebo mu chybí rozsah, který endpoint vyžaduje. |
Chybějící rozsah se hlásí stejně jako neznámý klíč, aby odpověď nikdy neprozradila,
zda klíč existuje. Na neúspěšnou autentizaci se odpovídá se záměrným krátkým
zpožděním; neopakujte 401 ve smyčce, opravte raději klíč nebo jeho rozsahy.