Appeler l'API REST : token, scopes, premier appel

Pour appeler l’API Videas : ouvrez vos Paramètres → Accès API, créez un token en cochant ses scopes et son expiration, puis authentifiez vos requêtes avec le header Authorization: Bearer <votre-token>. L’API REST couvre l’import de vidéos depuis un LMS, la synchronisation de métadonnées avec un CRM, la récupération de vos statistiques et l’automatisation de vos workflows de publication.

Prévoyez des connaissances de base en REST (méthodes HTTP, headers, JSON) et un client HTTP (curl, Postman, Insomnia…). Aucun rôle particulier n’est requis : les tokens sont personnels, chaque membre crée les siens. Une documentation interactive liste par ailleurs tous les endpoints disponibles.

Étape 1 : Accéder à la gestion des tokens

Les tokens API sont rattachés à votre compte utilisateur (pas à l’organisation). Chaque membre de votre équipe crée ses propres tokens — aucun rôle particulier n’est requis, seulement d’être connecté.

Depuis vos Paramètres, ouvrez la page Accès API (page Tokens API). L’écran affiche un en-tête avec trois compteurs : Total tokens, Tokens actifs, Expiration proche. En dessous, la liste de vos tokens existants (vide à votre première visite).

Important : comme les tokens sont personnels, ne partagez jamais vos tokens avec un collègue. Si plusieurs personnes ont besoin d’accéder à l’API, chacune crée ses propres tokens. C’est aussi ce qui permet de tracer correctement qui fait quoi via l’API.

Étape 2 : Créer un token

Cliquez sur Créer un token : la boîte de dialogue Créer un token API s’ouvre avec trois champs — un nom, les permissions, une expiration.

Nom du token

Donnez un nom descriptif indiquant à quoi le token va servir. Exemples :

Synchro CRM HubSpot
Import LMS - script nightly
Dashboard analytics interne
Postman tests dev local

C’est ce qui s’affiche dans la liste, et c’est précieux quand vous gérez plusieurs tokens en parallèle.

Permissions (scopes)

Les permissions (scopes) définissent ce que le token peut faire. Vous les cochez sous forme d’étiquettes ; au moins une est requise. Elles suivent la forme <ressource>:<action> :

Scope	Ce qu’il autorise
`users:read` · `users:write`	Lire / modifier les infos utilisateur
`assets:read` · `assets:write` · `assets:delete`	Lire / créer-modifier / supprimer des médias
`files:read` · `files:write` · `files:delete`	Lire / envoyer / supprimer des fichiers
`platforms:read` · `platforms:write`	Lire / modifier les chaînes
`billing:read` · `billing:write`	Lire / modifier la facturation
`helpdesk:read` · `helpdesk:write`	Lire / écrire côté centre d’aide

Principe du moindre privilège : ne cochez que les scopes strictement nécessaires à votre intégration. Un script qui n’a besoin que d’importer des vidéos ne doit pas avoir assets:delete. Vous limitez ainsi les dégâts en cas de fuite du token.

Expiration

Choisissez quand le token doit expirer :

Pas d’expiration : le token reste actif tant que vous ne le révoquez pas
30 / 60 / 90 jours : pour des intégrations temporaires (test, migration ponctuelle, mission)
1 an : compromis raisonnable pour les intégrations long terme

Bonne pratique : privilégiez une expiration définie plutôt que “Pas d’expiration”, même pour les intégrations long terme. Renouveler son token tous les ans ou tous les six mois est une rotation qui limite l’impact d’une compromission silencieuse.

Validez avec Créer le token.

Étape 3 : Copier la valeur du token

Après validation, la boîte Token créé affiche la valeur complète du token, une seule fois, avec l’avertissement « Assurez-vous de copier votre token maintenant. Vous ne pourrez plus le voir ensuite. »

Cliquez sur Copier le token et rangez-le immédiatement dans un gestionnaire de secrets ou dans votre application. Si vous fermez la boîte sans l’avoir copié, vous ne pourrez plus le récupérer : il faudra supprimer ce token et en créer un nouveau.

Mauvaise pratique à éviter absolument : ne collez jamais votre token dans un message Slack, un e-mail, un commit Git, ou un Google Doc partagé. Stockez-le exclusivement dans :

Un gestionnaire de secrets (1Password, Bitwarden, AWS Secrets Manager, Doppler…)

Une variable d’environnement lue par votre application au runtime

Un fichier .env non commité (ajouté à .gitignore)

Étape 4 : Effectuer un premier appel

L’API Videas est exposée à l’URL :

https://app.videas.com/api/external/

L’authentification se fait via le header Authorization: Bearer <votre-token>.

Exemple : lister vos médias

curl -H "Authorization: Bearer $VIDEAS_API_TOKEN" \
     https://app.videas.com/api/external/assets/

La réponse est en JSON, avec la liste des médias accessibles dans le périmètre des scopes du token.

Exemple en Python

import os
import requests

API_TOKEN = os.environ["VIDEAS_API_TOKEN"]
BASE_URL = "https://app.videas.com/api/external"

response = requests.get(
    f"{BASE_URL}/assets/",
    headers={"Authorization": f"Bearer {API_TOKEN}"},
)
response.raise_for_status()
assets = response.json()

Exemple en JavaScript (Node.js)

const response = await fetch('https://app.videas.com/api/external/assets/', {
  headers: {
    Authorization: `Bearer ${process.env.VIDEAS_API_TOKEN}`,
  },
})
const assets = await response.json()

Si la réponse est 401 Unauthorized, vérifiez : le préfixe Bearer, l’absence d’espace parasite, la validité du token (pas révoqué, pas expiré), les scopes (votre endpoint doit être couvert).

Étape 5 : Suivre l’utilisation des tokens

Dans la liste des tokens, chaque ligne affiche :

Nom + description
Préfixe : les premiers caractères du token, pour l’identifier sans exposer la valeur complète
Permissions : les scopes activés (chips), avec un compteur si plus de 2
Statut : Actif (vert) ou Révoqué (rouge)
Dernière utilisation : utile pour repérer les tokens dormants
Expire : date d’expiration, ou Jamais

L’en-tête de la page rappelle l’état global : combien de tokens vous avez, combien sont actifs, combien expirent dans les jours qui viennent. C’est l’écran à passer en revue trimestriellement dans une démarche d’hygiène des accès.

Étape 6 : Révoquer un token

Si un token est compromis, n’est plus utilisé, ou doit être renouvelé :

Dans la liste, trouvez le token concerné
Cliquez sur l’action Supprimer
Confirmez

⚠️ Action irréversible : le token devient immédiatement invalide. Tous les appels en cours échoueront en 401. Si l’application qui l’utilise n’a pas de fallback, prévoyez la création du remplaçant avant la révocation.

Documentation interactive de l’API

Pour explorer la liste exhaustive des endpoints, leurs paramètres, leurs schémas de réponse et leurs codes d’erreur, ouvrez la documentation API Videas. Elle est générée automatiquement depuis le code (OpenAPI / Swagger) — c’est donc toujours à jour avec ce que le serveur expose réellement.

Vous y trouverez notamment :

L’inventaire complet des endpoints (médias, espaces, collections, statistiques, partages, embeds…)
Les schémas JSON des objets reçus et envoyés
La possibilité de tester les appels directement depuis la doc en collant votre token

Bonnes pratiques de sécurité

Stockage

Ne jamais committer un token dans un dépôt Git (utilisez .env + .gitignore)
Utiliser un gestionnaire de secrets pour les environnements partagés (CI/CD, prod)
Lire les tokens depuis des variables d’environnement au runtime

Rotation

Définir une expiration sur tous les tokens (90 jours pour les usages courants, 1 an max pour les intégrations long terme)
Mettre en place une procédure de renouvellement documentée (qui, quand, comment)

Surveillance

Passer en revue la liste des tokens trimestriellement : révoquer les inactifs (champ Dernière utilisation qui ne bouge plus)
Surveiller les scopes trop larges et les réduire si possible
Documenter à quoi sert chaque token actif (au minimum dans la description)

Compromission

Si vous suspectez qu’un token a fuité (commit accidentel, partage par erreur, fichier de logs exposé…) : révoquer immédiatement, créer un nouveau token, mettre à jour les applications consommatrices

Un token API se partage-t-il entre collègues ?

Non, jamais. Les tokens sont rattachés à votre compte utilisateur, pas à l’organisation : chaque membre de l’équipe crée les siens, et aucun rôle particulier n’est requis pour cela.

C’est ce qui permet de tracer correctement qui fait quoi via l’API, et de révoquer l’accès d’une personne sans casser les intégrations des autres. Un token partagé, à l’inverse, rend toute révocation impossible sans interrompre tout le monde.

J’ai fermé la fenêtre sans copier mon token, que faire ?

Le créer à nouveau. La valeur complète n’est affichée qu’une seule fois, à la création — l’avertissement l’annonce explicitement — et Videas ne la conserve pas en clair. Il n’y a donc aucun moyen de la récupérer ensuite.

Supprimez le token devenu inutilisable et créez-en un nouveau. La liste n’affiche par la suite que son préfixe, les premiers caractères, qui servent à l’identifier sans exposer la valeur.

Où faut-il stocker un token API ?

Dans un gestionnaire de secrets (1Password, Bitwarden, AWS Secrets Manager, Doppler), dans une variable d’environnement lue au runtime, ou dans un fichier .env ajouté à .gitignore.

Jamais dans un message Slack, un e-mail, un commit Git ou un document partagé. Le commit accidentel est de loin la fuite la plus fréquente, et la plus durable : un token poussé une fois reste dans l’historique du dépôt même après suppression du fichier.

Faut-il donner une date d’expiration à ses tokens ?

Oui, même pour une intégration long terme. L’option Pas d’expiration existe, mais un token qui ne meurt jamais est un token dont personne ne se souvient — et dont une fuite silencieuse reste exploitable indéfiniment.

Comptez 90 jours pour les usages courants et un an au maximum pour les intégrations durables. Le renouvellement périodique est ce qui limite l’impact d’une compromission que vous n’auriez pas détectée.

Que faire si un token a fuité ?

Révoquez-le immédiatement, puis créez son remplaçant et mettez à jour les applications qui l’utilisaient. La révocation est instantanée et irréversible : tous les appels en cours échouent aussitôt en 401.

Dans le cas d’une intégration en production sans mécanisme de repli, l’ordre inverse est plus sûr : créez d’abord le nouveau token, déployez-le, puis supprimez l’ancien.

Que signifie une réponse 401 Unauthorized ?

Que l’authentification n’a pas été acceptée. Quatre causes, à vérifier dans cet ordre : le préfixe Bearer manquant dans le header, un espace parasite dans la valeur copiée, un token révoqué ou expiré, ou des scopes insuffisants pour l’endpoint appelé.

Les scopes sont la cause la moins évidente : un token qui ne porte que assets:read renverra une erreur sur une écriture, même s’il est parfaitement valide par ailleurs. C’est le prix du principe de moindre privilège — ne cochez que le nécessaire, mais sachez ce que vous avez coché.

En résumé

Les tokens API sont personnels, créés depuis Paramètres > Accès API
Configurez nom, description, scopes (<ressource>:<action>) et expiration
La valeur du token n’est affichée qu’une seule fois à la création — copiez-la immédiatement
L’API est exposée sur https://app.videas.com/api/external/, authentifiée par Authorization: Bearer <token>
La documentation interactive liste tous les endpoints disponibles
Appliquez le principe du moindre privilège sur les scopes et renouvelez régulièrement vos tokens
En cas de compromission, révoquez immédiatement et créez un nouveau token

Articles liés

Les captures sont prises sur Videas Academy, une chaîne d'exemple créée pour ce centre d'aide. Elle appartient à un client fictif, pas à Videas : votre chaîne porte votre nom, votre identité et vos tarifs.

Accéder à l'API Videas (développeurs)