# Autentizace

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

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](#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](chat.md) |
| `ayeto.conversation` | AYETO konverzace | [Konverzace](conversations.md) |
| `ayeto.assistant` | AYETO asistenti | Výpis [asistentů](assistants.md) a jejich avatarů |
| `ayeto.workflow` | AYETO workflow (čtení a spouštění) | Čtení a spouštění [workflow](workflows.md), běhy, schválení |
| `ayeto.workflow.write` | AYETO workflow (úpravy) | Vytváření, úpravy, publikování, import a mazání [workflow](workflows.md) |
| `ayeto.booster.database` | AYETO booster databáze (čtení) | Čtení záznamů [booster databáze](booster-database.md) |
| `ayeto.booster.database.write` | AYETO booster databáze (zápis) | Vytváření, úpravy a mazání záznamů, zámky |
| `ayeto.tts` | AYETO převod textu na řeč | [Převod textu na řeč](files-and-media.md#prevod-textu-na-rec) |
| `ayeto.data_loader` | AYETO text ze souboru | [Převod souboru na text](files-and-media.md#prevod-souboru-na-text) |

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.

## 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.