Portées
Les autorisations que votre application peut demander aux utilisateurs de Woupi, et le fonctionnement des autorisations accordées.
Portées disponibles
Les portées limitent ce qu’un jeton d’accès utilisateur peut faire. Votre application indique les portées dont elle a besoin dans le paramètre scope du flux d’autorisation ou du flux par code d’appareil (séparées par des espaces), et l’utilisateur voit la description de chacune sur l’écran de consentement. Les points de terminaison qui exigent une portée absente du jeton répondent 403 avec le message Missing scope: <scope>. Une portée inconnue fait échouer la requête avec invalid_scope.
| Portée | Ce qu'elle permet |
|---|---|
user:read:email | Lire l'adresse courriel de votre compte. |
user:read:follows | Voir la liste des chaînes que vous suivez. |
channel:read:followers | Voir la liste des personnes qui suivent votre chaîne. |
channel:read:subscriptions | Voir les abonnements actifs à votre chaîne. |
channel:manage:broadcast | Modifier le titre et la catégorie de votre diffusion. |
channel:read:stream_key | Voir l'URL de diffusion et la clé de stream de votre chaîne (permet de diffuser sur votre chaîne). |
chat:read | Lire les messages du clavardage en votre nom. |
chat:write | Envoyer des messages dans le clavardage en votre nom. |
moderator:manage:chat | Supprimer des messages et régler les modes du clavardage de votre chaîne. |
clips:write | Créer des clips en votre nom. |
drops:read | Voir les récompenses Drops que vous avez réclamées pour ce jeu et les marquer comme livrées. |
Les données publiques (utilisateurs, chaînes, diffusions, vidéos, catégories, paramètres du clavardage) n’exigent aucune portée et peuvent être lues avec n’importe quel jeton valide, y compris un jeton d’application.
Portées selon l’usage
| Vous voulez | Demandez | Accordée par |
|---|---|---|
| Lire l’adresse courriel de l’utilisateur qui se connecte | user:read:email | Cet utilisateur |
| Lister les chaînes suivies par un utilisateur | user:read:follows | Cet utilisateur |
Lister les suiveurs d’une chaîne ou recevoir les événements channel.follow | channel:read:followers | Le diffuseur |
Lister les abonnés ou recevoir les événements channel.subscribe et channel.subscription.gift | channel:read:subscriptions | Le diffuseur |
| Modifier le titre ou la catégorie d’une chaîne | channel:manage:broadcast | Le diffuseur |
Récupérer l’URL de diffusion et la clé de stream d’une chaîne (/v1/streams/key) | channel:read:stream_key | Le diffuseur |
Lire le clavardage avec un robot (channel.chat.message, channel.chat.message_delete) | chat:read | Le compte du robot (le user_id de l’abonnement) |
| Envoyer des messages de clavardage | chat:write | Le compte qui envoie |
| Supprimer des messages ou modifier les paramètres du clavardage | moderator:manage:chat | Le diffuseur |
| Créer des extraits | clips:write | L’utilisateur qui crée l’extrait |
| Permettre à un jeu de lire et de traiter les drops d’un joueur | drops:read | Le joueur |
Certains types d’événements n’exigent aucune portée : stream.online, stream.offline, channel.update, channel.chat_settings.update, channel.clip.create et channel.vod.ready. Consultez EventSub.
Ne demandez que le nécessaire
- Demandez le plus petit ensemble de portées qui permet à votre fonctionnalité de marcher. Les utilisateurs approuvent plus volontiers une liste courte, et un jeton compromis peut causer moins de dégâts.
- Demandez les portées supplémentaires plus tard, lorsque l’utilisateur active la fonctionnalité qui en a besoin, plutôt que toutes d’un coup à la première connexion.
- Lisez le champ
scopede la réponse de jeton, ou le tableauscopesrenvoyé par/oauth2/validate, pour savoir ce qui a réellement été accordé.
Cumul des autorisations
Lorsqu’un utilisateur autorise votre application, Woupi enregistre une autorisation pour cet utilisateur et cette application. Les autorisations se cumulent : si l’utilisateur accorde plus tard des portées supplémentaires, l’autorisation devient l’union des anciennes et des nouvelles portées. Lorsque toutes les portées demandées sont déjà accordées, l’écran de consentement est sauté (sauf si vous passez force_verify=true).
Chaque jeton porte les portées demandées au moment de son émission. L’actualisation conserve les mêmes portées; pour obtenir un jeton avec plus de portées, faites repasser l’utilisateur par le flux d’autorisation avec la liste complète dont vous avez besoin.
Remarque
Les abonnements aux événements vérifient l’autorisation accordée, pas un jeton : par exemple, un abonnement channel.follow exige que le diffuseur ait accordé channel:read:followers à votre application.
Lorsqu’un utilisateur déconnecte votre application
Les utilisateurs voient toutes les applications qu’ils ont autorisées dans l’onglet Sécurité de leurs paramètres Woupi et peuvent déconnecter chacune d’elles. La déconnexion :
- supprime l’autorisation;
- révoque tous les jetons d’accès et d’actualisation que votre application détient pour cet utilisateur;
- supprime vos abonnements aux événements qui dépendaient de l’autorisation de cet utilisateur (les abonnements webhook reçoivent d’abord un message
revocationavec le statutauthorization_revoked); - envoie un événement
user.authorization.revokeà votre application si vous y êtes abonné.
Votre application doit alors cesser d’agir pour cet utilisateur et lui demander une nouvelle autorisation s’il revient.