API REST et jetons d’API

Avec un jeton d’API, vos propres systèmes, par exemple un MAM, un CMS ou vos scripts, travaillent avec un espace de travail via l’API REST. L’API REST est incluse dans les formules Enterprise et OnPremise. La documentation de l’API décrit chaque route.

Formules
Enterprise et OnPremise
Qui crée les jetons
Chaque membre, pour lui-même ; les administrateurs voient et révoquent tous les jetons de l’espace de travail
Ce qu’un jeton peut faire
Ce que ses autorisations permettent, jamais plus que le rôle de son titulaire, dans un seul espace de travail

Ce que permet l’API

Via l’API, vos systèmes lisent les épisodes, les transcriptions et les clips, chargent des épisodes en plusieurs parties ou les importent depuis un stockage connecté, modifient des clips, les envoient en validation, les valident ou les renvoient, planifient et publient les clips validés, et lancent des tâches d’IA. Ils peuvent aussi gérer les kits de marque, l’équipe, les règles éditoriales et les webhooks, lire le journal d’audit et la consommation, récupérer les clips validés avec leurs fichiers pour un CMS et livrer des clips dans votre MAM ou DAM.

L’API suit les mêmes règles que l’application : rôles, validation, embargo et quota. Les tâches d’IA et les chargements sont décomptés du quota de votre organisation.

Créer un jeton d’API

Chaque membre de l’espace de travail peut créer des jetons pour lui-même.

  1. Ouvrez Settings → API.
  2. Cliquez sur Create token.
  3. Sous Name, indiquez à quoi sert le jeton, par exemple le système qui l’utilise.
  4. Sous Valid for, choisissez 30, 90, 180 ou 365 jours.
  5. Sous Permissions, décochez tout ce dont le système n’a pas besoin. Au départ, toutes les autorisations sont cochées.
  6. Cliquez sur Create.
  7. Cliquez sur Copy et conservez le jeton là où votre système garde ses secrets. ShowBits ne l’affiche que cette seule fois et n’en conserve qu’une empreinte.
  8. Cliquez sur Done.

Le jeton agit en votre nom, avec votre rôle, et uniquement dans cet espace de travail ; il ne peut jamais faire plus que ce que permet votre rôle. Vous pouvez avoir jusqu’à 20 jetons valides par espace de travail.

Capture d’écran de ShowBits : Créer un jeton d’API

Consulter et révoquer des jetons

La liste sous API tokens affiche chaque jeton avec son nom, la fin de sa valeur, son état (Active, Expired ou Revoked), qui l’a créé et quand, jusqu’à quand il est valable et quand il a été utilisé pour la dernière fois. Vous voyez vos propres jetons ; les administrateurs voient tous les jetons de l’espace de travail et peuvent les révoquer.

  1. Ouvrez Settings → API.
  2. Cliquez sur Revoke à côté du jeton.
  3. Confirmez avec Revoke. Les systèmes qui utilisent le jeton perdent immédiatement l’accès. Cette action est irréversible.

Un jeton prend également fin à son expiration et lorsque son titulaire quitte l’espace de travail, et il ne fonctionne que tant que la formule de votre organisation inclut l’API. Créez un nouveau jeton suffisamment tôt avant l’expiration de l’ancien.

Capture d’écran de ShowBits : Consulter et révoquer des jetons

Votre première requête

L’adresse de base et l’OpenAPI description se trouvent sur la même page que vos jetons. La description OpenAPI liste chaque route sous une forme lisible par une machine ; la documentation de l’API présente chaque route avec l’autorisation qu’elle requiert.

  1. Ouvrez Settings → API et copiez l’adresse qui suit Base address. Dans ShowBits Cloud, il s’agit de https://app.showbits.ai/api/v1.
  2. Envoyez le jeton avec chaque requête, dans l’en-tête Authorization: Bearer sbk_….
  3. Faites l’essai : curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/me renvoie votre nom, l’espace de travail du jeton avec son slug, les autorisations du jeton et sa date d’expiration.
  4. Utilisez le slug dans les chemins de l’espace de travail. Par exemple, curl -H 'Authorization: Bearer sbk_…' 'https://app.showbits.ai/api/v1/workspaces/talk-am-abend/clips?status=review' liste les clips en attente de validation dans l’espace de travail talk-am-abend ; il faut pour cela l’autorisation Read clips, texts, videos and subtitles.

Dans ShowBits OnPremise, l’adresse de base est celle de votre installation. Les réponses sont au format JSON en camelCase, avec les heures en UTC (ISO 8601) et les identifiants sous forme d’UUID.

Valider via l’API

Un système ne peut valider ou renvoyer des clips qu’avec un jeton disposant de l’autorisation Approve clips and send them back (clips:approve). Un tel jeton valide en votre nom : n’accordez donc cette autorisation qu’aux jetons qui en ont besoin. La boîte de dialogue le rappelle juste à côté : « This lets a system approve clips in your name. »

Chaque appel correspond à une étape de validation, comme un clic dans l’application : la réponse indique forwarded lorsque le clip passe à l’étape suivante, ou approved lorsqu’il est validé définitivement. Le système valide un clip par un POST sur la route du clip se terminant par /approve et le renvoie avec /reject, dans les deux cas avec un comment facultatif. Un clip renvoyé doit d’abord repartir en validation ; d’ici là, l’API répond par 409.

Limites, erreurs et pagination

Par jeton et par minute, ShowBits accepte 600 requêtes de lecture et 60 requêtes d’écriture. Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset indiquent où vous en êtes ; au-delà, la réponse est 429 avec Retry-After. Les erreurs sont renvoyées au format application/problem+json (RFC 9457) avec reason, un mot fixe d’après lequel votre système peut distinguer les cas : 401 aucun jeton valide, 403 autorisation ou rôle manquant, 404 inconnu ou dans un autre espace de travail, 409 impossible dans l’état actuel (par exemple notApproved ou embargo), 413 fichier trop volumineux, 422 saisie non valide, 429 limite ou quota.

Les listes sont paginées, avec jusqu’à 200 entrées par page (50 par défaut, à régler avec ?limit=). Pour la page suivante, transmettez la valeur nextCursor de la réponse dans le paramètre ?cursor=.

Actions via l’API dans le journal d’audit

Chaque modification effectuée avec un jeton figure dans le journal d’audit comme une action de son titulaire, avec la mention « through the API token » et le nom du jeton. La création et la révocation de jetons y sont également consignées.

  1. Ouvrez Settings → Security.
  2. Faites défiler la page jusqu’à Audit log.

Questions

Un jeton peut-il servir dans plusieurs espaces de travail ?

Non. Un jeton appartient à une personne et à un espace de travail. Pour un autre espace de travail, créez-y un jeton.

Je n’ai pas copié le jeton à temps. ShowBits peut-il l’afficher à nouveau ?

Non. ShowBits n’en conserve qu’une empreinte. Révoquez le jeton et créez-en un nouveau.

Que deviennent les jetons d’une personne qui quitte l’espace de travail ?

Ils prennent fin immédiatement. Les systèmes qui les utilisaient ont besoin d’un nouveau jeton, créé par une autre personne.

Un système peut-il connecter un stockage, des canaux ou des clés d’IA via l’API ?

Non. Les connexions, les clés d’IA, les données d’accès d’un MAM, les jetons d’API et la facturation sont configurés par une personne dans l’application.

Puis-je répéter une requête sans risque ?

Oui. Un POST peut comporter l’en-tête Idempotency-Key : par jeton et par clé, il n’est exécuté qu’une seule fois pendant 24 heures, et la même requête reçoit à nouveau la réponse enregistrée. PUT, PATCH et DELETE peuvent de toute façon être répétés.

Une évolution de l’API peut-elle perturber notre intégration ?

/v1 ne fait que s’enrichir : nouveaux champs, nouvelles routes et nouveaux événements. Ignorez les champs inconnus dans les réponses ; l’API refuse les champs inconnus dans les requêtes.

Nous avons la formule Creator ou Business. Pouvons-nous utiliser l’API ?

L’API REST est incluse dans Enterprise et OnPremise ; dans les autres formules, Settings → API propose Write to us. Dans toutes les formules, n8n, Zapier et Make se connectent sans l’API : voir n8n, Zapier et Make.