Začínáme

Autentizace

Vytváření API klíčů, jejich posílání s požadavky a výběr rozsahů.

Zobrazit jako Markdown

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:

  1. Zvolte nový, pojmenujte klíč (a volitelně přidejte popis).
  2. Vyberte rozsahy, které klíč potřebuje.
  3. 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:

text
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:

bash
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čce uni-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.