Tous

Authentification

Clés API Pro, tokens dashboard, signatures webhook et tokens ICS.

Dans cet article

Vue d’ensemble
Clé API Pro
Token dashboard
Signature webhook
Token ICS privé
Bonnes pratiques

Vue d’ensemble

Mécanisme	Plans	Rôle
Bearer Clerk	Plus, Pro	Dashboard, config webhooks, gestion clés API
Clé API nj_live_…	Pro	Appels REST /api/v1/… depuis un serveur
Secret webhook whsec_…	Plus, Pro	Vérifier les POST entrants (réception)
Token ICS (?token=)	Plus (cible)	Flux calendrier privé — URL secrète
Aucune	Tous	Lecture publique calendrier et events

L'onglet Développeur du dashboard (création clés, guide intégrations) est visible uniquement pour les calendriers Plus ou Pro.

Clé API Pro

Authentifiez vos requêtes REST /api/v1/… avec l'en-tête x-njanggo-api-key. Une clé = un calendrier, scopes limités, plan Pro actif requis.

curl -X GET "https://api.njanggo.com/api/v1/calendars/mon-collectif" \
  -H "x-njanggo-api-key: $NJANGGO_API_KEY"

En-tête

x-njanggo-api-keystringrequis

Clé secrète nj_live_… — préfixe affiché après création (nj_live_ + 8 car.)

Affichée une seule fois

Lors de la création, copiez la clé complète. Ensuite, seul le préfixe reste visible pour identification.

Gestion des clés (live)

Dashboard → Calendrier → Paramètres → Développeur (plan Pro) :

Endpoints gestion clés

GET    /api/calendars/:slug/api-keys/scopes
GET    /api/calendars/:slug/api-keys
POST   /api/calendars/:slug/api-keys        { name, scopes[] }
PATCH  /api/calendars/:slug/api-keys/:id    { name?, isActive? }
DELETE /api/calendars/:slug/api-keys/:id

Token dashboard (Bearer)

La configuration des webhooks, exports planifiés (cible), flux ICS (cible) et clés API se fait via le dashboard avec votre session connectée :

Authorization

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Clerk émis à la connexion sur njanggo.com — renouvelé automatiquement par le navigateur. Ne pas l'utiliser dans des scripts serveur longue durée : préférez les clés API Pro.

Pour tester dans la doc (Try It!) : DevTools → Network → requête /api/… → copier le header Authorization.

Vérifier la signature webhook

Format actuel (webhooks par événement, live) — en-têtes envoyés par Njanggo :

En-tête	Description
X-Njanggo-Webhook-Event	Type : guest.registered, checkin.created, event.updated, …
X-Njanggo-Webhook-Timestamp	Unix timestamp (secondes)
X-Njanggo-Webhook-Signature	t=<timestamp>,v1=<hex> — HMAC-SHA256 de "{timestamp}.{rawBody}"
Content-Type	application/json

Node.js — format actuel (live)

import crypto from 'crypto';

function verifyNjanggoWebhook(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const payload = `${parts.t}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
}

Format cible (webhooks calendrier Plus, à venir) — X-Njanggo-Event, X-Njanggo-Signature: sha256=<hex> (HMAC du corps brut), X-Njanggo-Delivery-Id pour l'idempotence. Détail : Webhooks → Signature.

Utilisez le corps brut de la requête (buffer), pas un JSON re-sérialisé.

Token ICS privé (cible Plus)

Le flux ICS privé protégera les événements non publics via un token long dans l'URL :

GET /api/calendars/:slug/events.ics?token=VOTRE_TOKEN

Pas encore déployé. Ce token n'utilise pas l'en-tête API — traitez l'URL comme un secret. Voir Flux ICS.

Bonnes pratiques

1
Serveur uniquement
Clés API et secrets webhook uniquement côté backend.
2
Scopes minimums
Créez des clés avec le strict nécessaire (lecture seule si possible).
3
Rotation
Créez une nouvelle clé → migrez → révoquez l'ancienne.
4
HTTPS obligatoire
Les URLs webhook doivent être HTTPS en production.

Étapes suivantes

Comment consommer l’API

Guide pas à pas.

Clés API Pro

Scopes et gestion.

Webhooks

Actuel vs cible.