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 :
Code
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.frn'accepte paswww.concession.fr; - ou correspondre à un joker déclaré explicitement :
*.concession.fracceptewww.concession.fr, mais pasconcession.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
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.