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

Nouveau sur Videas ? Commencez par Premiers pas : tour de l’interface.

Vous voulez importer des vidéos depuis votre LMS, synchroniser vos métadonnées avec un CRM, récupérer vos statistiques pour les afficher dans un dashboard interne, ou automatiser vos workflows de publication ? Videas expose une API REST complète, sécurisée par tokens, avec un système de scopes granulaires et une documentation interactive. Ce guide vous accompagne de la création de votre premier token au premier appel réussi.

Prérequis

• Un compte Videas
• Des connaissances de base en REST API (méthodes HTTP, headers, JSON)
• Un outil pour faire des requêtes : curl, Postman, Insomnia, ou n’importe quel client HTTP

Ce que vous allez apprendre

• Accéder à la gestion des tokens API dans Videas
• Créer un token avec nom, scopes et expiration
• Effectuer votre premier appel API
• Suivre l’utilisation et révoquer un token
• Appliquer les bonnes pratiques de sécurité

É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 peut créer ses propres tokens.

1. Cliquez sur votre avatar en haut à droite
2. Ouvrez Paramètres
3. Dans le menu latéral, cliquez sur Accès API (sous-rubrique Développeur)

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 : une boîte de dialogue s’ouvre avec quatre champs.

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.

Description (optionnel)

Une ligne de contexte supplémentaire. Utile pour :

• Le propriétaire technique côté code (“géré par le service Data, contact: data@…”)
• Le dépôt où le token est utilisé (“repo gitlab…/etl-videas”)
• La raison d’existence du token

Permissions (scopes)

Les scopes définissent ce que le token peut faire. Ils sont organisés par ressource sous la forme <ressource>:<action>. Voici les principaux disponibles :

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

⚠️ Critique : la valeur complète du token apparaît une seule fois, juste après la création.

La boîte de dialogue affiche le token sous forme vds_xxxxxxxxxxxx (avec un bouton Copier). Copiez-le immédiatement dans un gestionnaire de secrets ou directement dans votre application.

Si vous fermez la boîte sans avoir copié le token : vous ne pourrez plus le récupérer. Vous devrez révoquer 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.fr/api/external/

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

Exemple : lister vos médias

curl -H "Authorization: Bearer vds_xxxxxxxxxxxx" \
     https://app.videas.fr/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.fr/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.fr/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 (vds_xxxxx...), 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é :

1. Dans la liste, trouvez le token concerné
2. Cliquez sur l’action Supprimer
3. 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

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.fr/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

• Documentation API Videas
• Gérer les rôles et permissions
• Gérer votre organisation Videas