Guide développeur
Référence des portées
Les portées de permission fines vous permettent de limiter ce à quoi une clé d'API ou un client OAuth peut accéder dans un espace de travail.
Vue d'ensemble
Les portées sont des chaînes séparées par des espaces attachées à une clé d'API ou à un client OAuth. À l'arrivée d'une requête, l'API valide les portées du jeton par rapport à l'opération demandée. Le modèle est celui de GitHub et Stripe : familier, auditable et simple à raisonner.
Les portées sont facultatives. Si aucune n'est spécifiée, l'identifiant dispose d'un accès complet à l'espace de travail (équivalent à un admin). Nous recommandons d'attribuer le minimum de portées nécessaires à chaque intégration.
Portées
| Portée | Ce qu'elle autorise | Méthodes | Points de terminaison |
|---|---|---|---|
polls:read | Lire les sondages, leur contenu et leurs métadonnées. | GET | /polls, /polls/{id} |
polls:write | Créer, modifier et supprimer des sondages. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | Lire les résultats agrégés par diapositive et la liste des votants. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | Envoyer des réponses et des votes aux sondages. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | Créer et piloter des sessions en direct. | POST | /sessions, /sessions/{id}/control |
sessions:read | Lire l'état d'une session en direct (statut, diapositive courante, nombre de participants). | GET | /sessions/{id} |
media:write | Téléverser et relayer des médias (images, YouTube) pour les questions. | POST | /media |
export:read | Télécharger les résultats en CSV ou en rapport PDF. | GET | /polls/{id}/export |
ai:write | Utilisez l'IA pour générer le contenu des sondages. | POST | /polls/{id}/branch |
Portées sur les clés d'API
Les portées des clés d'API sont appliquées à chaque requête. Une clé créée avec un ensemble de portées non vide ne peut appeler que les points de terminaison couverts : une requête nécessitant une portée absente renvoie 403 insufficient_scope. Une clé créée sans portée dispose d'un accès complet à l'espace de travail (voir Par défaut ci-dessous). Attribuez les portées à la création dans le portail développeur.
Portées sur les clients OAuth
Les clients OAuth appliquent les portées au moment de l'émission du jeton. Lorsque vous appelez POST /api/oauth/token avec un paramètre scope, seules les portées attribuées au client à sa création sont accordées. Demander une portée non attribuée la retire silencieusement du jeton.
Si aucune scope n'est envoyée dans la requête de jeton, le jeton hérite de toutes les portées attribuées au client (ou d'un accès complet si le client n'en a aucune).
Consultez le guide OAuth 2.0 pour une procédure de configuration complète.
Par défaut (aucune portée spécifiée)
Les identifiants sans portée attachée disposent d'un accès complet à l'espace de travail, équivalent à un admin. À utiliser pour :
- L'automatisation personnelle sur un espace de travail dont vous êtes propriétaire
- Le prototypage et le développement
Pour les intégrations en production partagées entre équipes ou avec des tiers, spécifiez toujours les portées minimales requises.
Vous avez encore des questions ?
Notre équipe se fera un plaisir de vous aider.