Authentification et identifiants

La clé API

Chaque agent API porte sa propre clé (préfixe ak_), visible dans ses paramètres. Passez-la sur chaque requête :

Authorization: Bearer ak_votre_cle

Statut	Cause
401	En-tête Authorization absent ou mal formé.
403	Clé invalide ou révoquée, agent désactivé, ou clé utilisée sur l’URL d’un autre espace que le sien.

Le bouton « Régénérer » des paramètres de l’agent révoque la clé immédiatement — l’ancienne cesse de fonctionner dès l’enregistrement. Prévoyez la mise à jour de votre configuration avant de régénérer en production.

La clé est un secret

Elle donne accès en lecture et en écriture aux conversations de l’agent. Stockez-la côté serveur (variable d’environnement, coffre de secrets) — jamais dans un client mobile ou du JavaScript navigateur.

Vos identifiants, pas les nôtres

L’API ne révèle jamais d’identifiants internes. Les champs id, thread.id et contact.id portent des identifiants opaques propres à l’agent : soit les valeurs que vous fournissez via les en-têtes ci-dessous, soit des UUID v7 générés par Assilya. Ce sont eux qui servent de clés dans les URLs (/api/message/{messageId}, /api/threads/{key}…).

En-tête	Rôle
X-Assilya-Thread	Votre identifiant de conversation (191 caractères max). Tous les messages qui le partagent rejoignent la même conversation ; sans lui, chaque message en ouvre une nouvelle.
X-Assilya-Message	Votre identifiant de message (191 caractères max, unique par agent — un doublon est rejeté). Sur POST /api/message, il identifie le message entrant ; sur POST …/answer, le message sortant créé.
X-Assilya-User-Id	L’identifiant du contact côté agent.
X-Assilya-User-Email	E-mail du contact — sert à le retrouver ou à le créer.
X-Assilya-User-Name	Nom du contact, appliqué à sa création.

Les noms accentués

Un en-tête HTTP transporte des octets, pas du texte : envoyé tel quel depuis un navigateur, « Mara Götz » arrive corrompu (« Mara G?tz »), et un nom contenant un caractère hors Latin-1 (« Łukasz », « Ελένη », « 王 ») fait échouer l’appel.

Encodez donc toute valeur non ASCII en mot encodé RFC 2047, le format des en-têtes d’e-mail :

X-Assilya-User-Name: =?UTF-8?B?TWFyYSBHw7Z0eg==?=

soit =?UTF-8?B? + le base64 de la valeur en UTF-8 + ?=. Assilya décode l’en-tête à réception. L’UTF-8 brut reste accepté si votre client peut l’émettre (appel serveur à serveur) ; le widget chatbot, lui, applique cet encodage automatiquement.

Le contact et son id

À la première soumission, Assilya résout le contact à partir des en-têtes X-Assilya-User-* (ou en crée un) et lui attribue un id côté agent, renvoyé dans contact.id dès la réponse 202.

Stockez cette valeur et renvoyez-la via X-Assilya-User-Id sur les appels suivants : le rattachement est alors direct, sans repasser par la résolution e-mail/téléphone. Les endpoints GET /api/contacts et GET /api/contacts/{contactId} permettent d’interroger cet annuaire (recherche partielle par nom, e-mail, téléphone).