Lister les scopes disponibles

Endpoint public : renvoie le catalogue complet des scopes avec leur description.

Requête exemple

"null"

Réponse exemple

"{\"scopes\":[{\"scope\":\"address_book:read\",\"description\":\"Lire les contacts du carnet d'adresses.\"},{\"scope\":\"analytics:read\",\"description\":\"Consulter les statistiques d'usage du workspace.\"},{\"scope\":\"api_keys:manage\",\"description\":\"Créer, lister, révoquer et faire tourner les clés API.\"},{\"scope\":\"audit:export\",\"description\":\"Exporter le journal d'audit complet.\"},{\"scope\":\"members:invite\",\"description\":\"Inviter de nouveaux membres dans le workspace.\"},{\"scope\":\"members:manage\",\"description\":\"Gérer les rôles et retirer des membres.\"},{\"scope\":\"transfers:read\",\"description\":\"Lire les métadonnées et le contenu des transferts.\"},{\"scope\":\"transfers:write\",\"description\":\"Créer et envoyer des transferts de fichiers.\"},{\"scope\":\"workspace:billing\",\"description\":\"Gérer l'abonnement et accéder aux factures.\"}]}"

GET /v1/api-keys/scopes renvoie le catalogue complet des scopes (permissions) disponibles pour les clés API Coffrify, tel que stocké dans la table de référence coffrify_api_scopes. Chaque entrée associe l'identifiant d'un scope (ex. transfers:read) à sa description lisible. C'est l'endpoint que le tableau de bord interroge pour construire la boîte de dialogue de création de clé, et celui qu'un intégrateur appelle pour découvrir dynamiquement les permissions octroyables plutôt que de les coder en dur. Comportement notable : la liste est triée par ordre alphabétique croissant du champ `scope`, et l'endpoint est volontairement en lecture seule et non sensible (il ne révèle aucune donnée du workspace, uniquement la nomenclature publique des permissions).

Authentification

Aucune authentification n'est requise. Contrairement aux autres routes /v1/api-keys/* (qui exigent le scope api_keys:manage), ce handler n'utilise pas l'enveloppe withApiHandler : il lit directement le référentiel via le client de service et n'impose ni clé API, ni scope, ni contexte de workspace. Vous pouvez donc appeler cet endpoint sans en-tête Authorization. C'est intentionnel : connaître la liste des permissions possibles ne divulgue aucune information sensible.

Paramètres de requête

Cet endpoint n'accepte aucun paramètre de requête. Il n'y a ni filtre, ni recherche, ni pagination : l'intégralité du catalogue (43 scopes au moment de l'écriture) est renvoyée en un seul appel.

Paramètre	Type	Requis	Description
—	—	—	Aucun paramètre n'est lu par le handler. Tout paramètre de requête transmis est simplement ignoré.

Réponse

La réponse est un objet JSON contenant une seule clé scopes, un tableau d'objets triés alphabétiquement par scope. Chaque objet expose exactement deux champs : scope (l'identifiant canonique de la permission, au format ressource:action, ex. members:invite) et description (le texte explicatif associé). Si la requête vers la base échoue, le handler renvoie un tableau vide plutôt qu'une erreur : un appelant doit donc traiter scopes: [] comme un cas possible (catalogue momentanément indisponible) et non comme "aucune permission n'existe".

Champ	Type	Description
scopes	array	Tableau des scopes disponibles, trié par `scope` croissant. Vide si la lecture du référentiel échoue.
scopes[].scope	string	Identifiant canonique de la permission, ex. `transfers:write`, `workspace:billing`.
scopes[].description	string	Description lisible du périmètre couvert par le scope.

Erreurs

Cet endpoint est conçu pour ne quasiment jamais échouer de façon visible : il ne valide aucune entrée et avale une éventuelle erreur de base en renvoyant une liste vide. Les seules erreurs possibles relèvent du transport ou de la plateforme.

Code HTTP	Quand	Comment résoudre
200	Cas nominal : le catalogue est renvoyé (`scopes` peut être un tableau plein ou vide).	Aucune action. Si `scopes` est vide, considérez le référentiel comme temporairement indisponible et réessayez plus tard.
405	Méthode autre que GET (POST, PATCH, DELETE...) sur cette route.	Utilisez exclusivement le verbe GET.
5xx	Indisponibilité de l'infrastructure (Next.js / Supabase) avant l'exécution du handler.	Erreur transitoire : réessayez avec un backoff exponentiel.

Voir aussi

POST/v1/api-keysCréer une clé API en sélectionnant un sous-ensemble des scopes renvoyés ici (MFA requise pour les scopes à risque élevé).GET/v1/api-keysLister les clés existantes du workspace avec les scopes effectivement attachés à chacune.POST/v1/api-keys/{id}/rotateFaire tourner le secret d'une clé existante en conservant ses scopes.