# Clés et jetons

Chaque **déploiement** (un client final, un site, un avatar, une formule) reçoit deux sortes de clés. Une conversation ouverte reçoit en plus son propre **jeton**.

| | Où | À quoi elle sert |
| --- | --- | --- |
| **Clé publique** `pk_…` | dans la page web, visible | ouvrir une conversation, lire la fiche de l'avatar. **Seulement depuis les pages déclarées** |
| **Clé secrète** `sk_…` | **jamais dans un navigateur** : sur votre serveur | ouvrir une conversation sans page (application, borne), lire la consommation |
| **Jeton de conversation** | là où la conversation a été ouverte | questions, voix, transcription, renouvellement et fin de la conversation |

Les trois s'envoient de la même façon :

```http
Authorization: Bearer <clé ou jeton>
```

## Quelle clé pour quelle route

| Route | Clé publique | Clé secrète | Jeton |
| --- | :---: | :---: | :---: |
| `GET /v1/health` | sans clé | sans clé | sans clé |
| `GET /v1/me` | ✓ | ✓ | |
| `GET /v1/avatars/{avatar_id}` | ✓ | ✓ | |
| `POST /v1/conversations` | ✓ | ✓ | |
| `POST /v1/conversations/{id}/token` | | | ✓ |
| `POST /v1/conversations/{id}/end` | | | ✓ |
| `POST /v1/conversations/{id}/messages` | | | ✓ |
| `POST /v1/conversations/{id}/speech` | | | ✓ |
| `POST /v1/conversations/{id}/transcriptions` | | | ✓ |
| `GET /v1/usage` | | ✓ | |

## Pages déclarées

La clé publique n'est acceptée que depuis les pages déclarées pour le déploiement. Le nom d'hôte de l'en-tête `Origin` doit être :

- **exactement** l'un des noms déclarés : `concession.fr` n'accepte **pas** `www.concession.fr` ;
- ou correspondre à un **joker déclaré explicitement** : `*.concession.fr` accepte `www.concession.fr`, mais pas `concession.fr`.

Sinon : `403 origin_not_allowed`. Un jeton reste lié à la page qui l'a obtenu : utilisé depuis une autre page, ou après que la page a été retirée du déploiement, il est refusé de la même façon.

## Essais et production

| Environnement | Adresse | Clés |
| --- | --- | --- |
| Essais | `https://api-dev.atwimi.com/v1` | `pk_test_…`, `sk_test_…` |
| Production | `https://api.twimi.ai/v1` (à venir) | `pk_live_…`, `sk_live_…` |

Une clé de test est refusée en production, et une clé de production en essais (`401 invalid_key`).

## Garder ses clés

:::danger{title="Une clé n'est montrée qu'une fois"}

Twimi n'en garde qu'une empreinte : une clé perdue se **remplace**, elle ne se retrouve pas.

:::

- La clé secrète ne quitte jamais votre serveur : ni dans le code d'une page, ni dans une application mobile, ni dans un dépôt de code.
- Une clé **révoquée** cesse de fonctionner immédiatement, et les conversations qu'elle a ouvertes s'arrêtent dans la minute, même avec un jeton renouvelé (`401 invalid_key`).

## CORS

Les pré-requêtes `OPTIONS` sont acceptées. La réponse à une vraie requête n'autorise que l'origine acceptée par la clé publique (`Access-Control-Allow-Origin` = la page, `Vary: Origin`). Pas de cookies.