Authentification

Chaque requête porte une clé secrète. Une clé appartient à une organisation, a des permissions limitées et peut être remplacée sans coupure.

Envoyer la clé

En-tête HTTP

Authorization: Bearer sk_live_…

Toutes les routes l’exigent, sauf GET /v1/health et GET /v1/openapi.json. Une clé absente, invalide, révoquée ou expirée renvoie 401 unauthorized.

Uniquement depuis votre serveurNe placez jamais une clé dans le code d’une page web, d’une application mobile ou d’un dépôt de code. Rangez-la dans les variables d’environnement secrètes de votre serveur.

Permissions

Choisissez à la création les permissions dont la clé a besoin, et pas plus. Une permission manquante renvoie 403 insufficient_scope.

Permission	Autorise
`videos:read`	Lire les vidéos et les informations de l’organisation
`videos:write`	Modifier, supprimer, relancer les vidéos ; sous-titres
`uploads:write`	Créer, terminer et annuler des envois
`playback:write`	Créer, lire et révoquer des sessions de lecture (liens et progression)
`webhooks:manage`	Gérer les webhooks et leurs envois
`usage:read`	Lire la consommation

Exemple : le serveur qui affiche les cours n’a besoin que de playback:write ; l’outil de gestion des leçons, de uploads:write et videos:read.

Remplacer une clé

POST /v1/api-keys/rotate crée une nouvelle clé (affichée une seule fois) avec les mêmes permissions. L’ancienne continue de fonctionner pendant graceSeconds (24 h par défaut, 7 jours au plus) : vous déployez la nouvelle sans interruption. Votre équipe peut aussi créer, remplacer et révoquer les clés dans l’espace client, rubrique Développeurs.

Terminal

curl -X POST https://api.vidoum.com/v1/api-keys/rotate \
  -H "Authorization: Bearer $VIDOUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "graceSeconds": 86400 }'

Bonnes pratiques

Une clé par usage (site, outil interne, environnement de test), pour pouvoir en révoquer une sans toucher aux autres.
Une clé de test distincte, aux permissions réduites, pour vos essais : il n’existe pas encore d’environnement de test séparé.
En cas de fuite : révoquez la clé immédiatement dans l’espace client, puis créez-en une nouvelle.
Chaque réponse contient un en-tête X-Request-Id : conservez-le dans vos journaux et indiquez-le au support.