Authentification et portées

Chaque requête porte une clé d’API de votre espace. La clé dit qui appelle, dans quel espace, en production ou en test, et ce qu’elle a le droit de faire.

Chaque requête porte une clé d’API dans l’en-tête Authorization: Bearer <clé>, jamais dans l’URL. Une clé vz_<préfixe>_… agit en production. Une clé vz_test_<préfixe>_… agit en mode test : aucun SMS ni e-mail ne part, et la session n’est pas facturée. Une clé a des portées (sessions:read, sessions:write, webhooks:manage) et peut expirer ou être révoquée ; GET /me la décrit. Chaque opération dit la portée qu’elle exige. mcp, vision (analyse d’image par le modèle de vision) et rag (recherche dans votre documentation) servent aux agents vocaux : voir « Agents vocaux (MCP) ». Son préfixe (8 caractères, lettres minuscules et chiffres) est public et repère la clé au back-office ; le secret ne s’affiche qu’une fois, à la création.

curl https://api.vizalia.ai/v1/sessions \
  -H "Authorization: Bearer vz_k7m2p9xq_…"

Vérifier une clé

GET /me ne demande aucune portée : c’est le test d’authentification le plus simple, et celui qu’attendent les outils sans code. La réponse décrit la clé utilisée.

GET /me, réponse

{
  "object": "api_key",
  "key_prefix": "k7m2p9xq",
  "label": "CRM, test",
  "livemode": false,
  "scopes": ["sessions:read", "sessions:write", "webhooks:manage"],
  "expires_at": null,
  "space": { "id": "…", "name": "…" }
}

Une clé absente, inconnue, révoquée ou expirée reçoit 401 unauthorized ; une clé à qui manque la portée de la route, 403 insufficient_scope.

Les portées

Une clé n’ouvre que les routes de ses portées. Donnez à chaque clé le minimum : un outil qui ne fait que créer des sessions et lire leur rapport n’a pas besoin de webhooks:manage.

Portée	Ce qu'elle ouvre
sessions:read	GET /sessions GET /sessions/{session_id} GET /sessions/{session_id}/photos GET /sessions/{session_id}/videos GET /sessions/{session_id}/documents GET /sessions/{session_id}/measurements GET /sessions/{session_id}/report GET /journeys GET /journeys/{journey_id} GET /brands GET /usage GET /events GET /events/{event_id}
sessions:write	POST /sessions POST /sessions/{session_id}/resend POST /sessions/{session_id}/end POST /sessions/{session_id}/simulate
webhooks:manage	GET /webhook_endpoints POST /webhook_endpoints GET /webhook_endpoints/{endpoint_id} PATCH /webhook_endpoints/{endpoint_id} DELETE /webhook_endpoints/{endpoint_id} POST /webhook_endpoints/{endpoint_id}/test POST /webhook_endpoints/{endpoint_id}/rotate_secret
mcp	Le serveur MCP des agents vocaux.
vision	L'analyse d'image par le modèle de vision, pour les agents vocaux.
rag	La recherche dans votre documentation, pour les agents vocaux (outils rag_…).
aucune	GET /me

Garder la clé secrète

• Serveur à serveur seulement : la clé ne va jamais dans du code exécuté par un navigateur, une application distribuée, un dépôt de code ou des journaux.
• Dans l’en-tête, jamais dans l’URL : les URL sont journalisées par les serveurs et les équipements intermédiaires.
• Dans un gestionnaire de secrets, lisible par les seuls composants qui s’en servent.
• Une clé par environnement : jamais de clé de production en test, ni l’inverse.
• Révoquez sans attendre une clé exposée ou suspecte, dans le back-office, puis créez-en une autre.

Attention

Le lien du client (join_url) et le lien du poste conseiller (advisor_url) donnent accès à la session : traitez-les comme des secrets, ne les journalisez pas.