Authentification API
L'API Vicket expose deux modes d'authentification. Chacun est lié à une audience différente et à une surface différente de l'API. Les mélanger est rejeté à l'entrée.
Cookie de session (dashboard)
Le dashboard agent hébergé authentifie les utilisateurs avec un cookie de session émis après une connexion adossée à WorkOS (email + mot de passe ou Google/GitHub). Après une connexion réussie, l'utilisateur est redirigé vers /v1/auth/callback?code=... qui échange le code, pose un cookie vicket_session (HttpOnly, Secure, SameSite=Lax), et redirige dans le dashboard.
Le cookie ne porte aucune permission en lui-même : il identifie l'utilisateur, et chaque requête est autorisée côté serveur contre la matrice de rôles & permissions.
Vous n'appelez jamais les endpoints à session depuis votre code. Ils alimentent le dashboard sur vicket.app.
Clé du site (pk_...)
Les endpoints publics sous /support/v1/... acceptent une clé publiable liée au site dans l'en-tête X-Vicket-Key :
GET /support/v1/help/articles HTTP/1.1
Host: api.vicket.app
X-Vicket-Key: pk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
La clé est validée et résolue à chaque requête : le serveur hashe la valeur présentée et cherche ce hash pour trouver le site. Aucun identifiant de site dans l'URL ; la clé EST l'identité, et tout ce qu'elle lit ou crée est limité à son site.
La clé est publiable : elle est conçue pour partir dans le navigateur. Deux garde-fous côté serveur rendent ça sûr : la liste d'origins ci-dessous et les limites de débit par site. Voir clés API pour la création, la rotation et le format.
CORS
Les endpoints publics répondent avec un Access-Control-Allow-Origin reflétant l'Origin de la requête, uniquement si cette origin figure dans la liste autorisée du site. Tout le reste ne reçoit aucun en-tête CORS (le navigateur refuse la réponse).
La liste se configure par site dans le dashboard sous Websites, votre site, Origins. Pas de wildcard : listez chaque origin exacte (schéma + hôte + port).
{
"origins": [
"https://app.acme.com",
"https://staging.acme.com",
"http://localhost:3000"
]
}
Erreurs
Les échecs d'authentification utilisent une forme d'erreur stable :
{
"error": {
"code": "auth.unauthorized",
"message": "Invalid or missing credentials."
}
}
Codes courants : auth.unauthorized (identifiants absents ou invalides), auth.forbidden (authentifié mais non autorisé).