Authentification

Comment obtenir, faire tourner et utiliser les clés API pour l'API RefCampaign.

Chaque endpoint authentifié attend un JWT Bearer dans le header Authorization. Les clés sont émises depuis le tableau de bord marchand, scopées à votre compte et signées par RefCampaign.

Générer une clé API

Ouvrez Paramètres → Clés API dans le tableau de bord.
Cliquez sur Créer une clé API et donnez-lui un nom descriptif (ex. production-server, ci-backfill).
Copiez le token. Le tableau de bord ne l'affiche qu'une fois — il n'y a pas de récupération.
Stockez le token dans un gestionnaire de secrets (Vercel, AWS Secrets Manager, GitHub Actions secrets…). Traitez-le comme un mot de passe.

Utiliser une clé

Envoyez le token sur chaque requête API :

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Exemple curl :

curl https://app.refcampaign.com/api/v1/campaigns \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY"

Le token est opaque pour votre application. Ne le parsez pas — son format peut changer entre les versions.

Durée de vie du token

Les clés API n'expirent pas par défaut. Elles restent valides jusqu'à révocation depuis le tableau de bord.

Si vous avez besoin de tokens courts à rotation (un contrôle de sécurité courant), faites la rotation vous-même :

Générez une nouvelle clé.
Déployez la nouvelle valeur sur vos serveurs.
Révoquez l'ancienne clé une fois le déploiement terminé.

Dans Paramètres → Clés API, cliquez Révoquer à côté de la clé. Les sessions actives sur cette clé échouent immédiatement avec 401. La révocation est définitive — pas de réactivation possible.

Une clé révoquée renvoie :

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Endpoints publics

Quelques endpoints acceptent du trafic anonyme (rate-limité par IP) :

POST /api/v1/track/click — suivi des clics depuis le SDK navigateur.
POST /api/v1/track/identify — binding session-vers-client.
POST /api/v1/affiliates/signup — inscription publique d'affiliés.
GET /api/v1/campaigns/{id}/public — profil public d'une campagne pour les landing pages.

Ces endpoints n'exigent PAS de header Authorization. Ils ont des limites de taux plus strictes et rejettent les payloads malformés avec la même enveloppe d'erreur.

Checklist sécurité

Ne committez jamais une clé dans git

Même dans un dépôt privé, les clés finissent dans les logs CI, les branches archivées et les forks. Utilisez les variables d'environnement et un gestionnaire de secrets — et faites tourner immédiatement si une clé a été commitée par accident.

Une clé dédiée par environnement. Ne partagez pas la clé production avec staging ou local dev.
Faites tourner après une fuite suspectée. Générez une nouvelle clé, déployez-la, révoquez l'ancienne.
Limitez le rayon d'impact. Si un service ne lit que les commissions, vous pourrez à terme scoper la clé sur cette surface — pour l'instant, traitez chaque clé comme un accès complet au compte.