Référence des scopes

Chaque clé API Coffrify porte un ensemble de scopes qui décrivent précisément ce qu'elle a le droit de faire. Un scope autorise une action sur une famille de ressources, et l'API refuse toute requête dont le scope requis n'est pas couvert par la clé. Cette page décrit la forme des scopes, la manière dont les caractères génériques (* et resource:*) élargissent une autorisation, les grandes familles disponibles, et la liste des scopes à risque élevé qui exigent une étape de vérification renforcée (MFA) au moment de créer la clé.

La forme ressource:action

Un scope suit toujours la forme ressource:action. La partie ressource désigne la famille concernée (transfers, webhooks, members, etc.) et la partie action décrit l'opération autorisée. Les actions les plus courantes sont read (lecture), write (création et modification) et manage (gestion complète, y compris la suppression et la configuration). Certaines familles ajoutent des actions spécifiques, comme download pour les transferts, invite pour les membres ou export pour l'audit et le RGPD.

• transfers:read autorise la lecture des transferts.
• transfers:write autorise la création et la modification des transferts.
• webhooks:manage autorise la gestion complète des endpoints de webhook.
• members:invite autorise uniquement l'envoi d'invitations, sans gérer les membres existants.

Le wildcard * et resource:*

Deux formes génériques permettent d'élargir une autorisation sans énumérer chaque scope. Le wildcard global * satisfait n'importe quel scope requis : une clé qui le porte peut appeler tous les endpoints. Le wildcard de ressource resource:* satisfait toute action sur cette ressource : par exemple webhooks:* couvre webhooks:read et webhooks:manage. La vérification suit un ordre simple : le wildcard * d'abord, puis la correspondance exacte du scope demandé, puis le wildcard de ressource resource:*.

Les grandes familles de scopes

Les scopes se regroupent par famille. Le tableau ci-dessous récapitule les familles principales et les actions typiques de chacune. La lecture (read) reste toujours l'action la moins privilégiée, tandis que manage confère le contrôle complet de la ressource.

Scopes à risque élevé et étape MFA

Certains scopes confèrent un contrôle administratif sur le workspace : gestion des membres, des sessions, des clés API, des domaines, ou export de données sensibles. Créer une clé qui contient l'un de ces scopes à risque élevé exige une étape de vérification supplémentaire : vous devez fournir un code MFA dans le champ mfa_code de la requête POST /v1/api-keys. Sans ce code, la création est refusée.

• members:manage : gérer les membres du workspace.
• sessions:manage : révoquer des sessions actives.
• api_keys:manage : créer, faire tourner et supprimer des clés API.
• workspace:manage : modifier les paramètres du workspace.
• domains:manage : gérer les domaines personnalisés.
• audit:export : exporter le journal d'audit.
• gdpr:export : exporter des données personnelles.
• workspace:billing : gérer la facturation et l'abonnement.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
// Cle restreinte limitee a la lecture/ecriture des transferts
const key = await coffrify.apiKeys.create({
  name: 'Service transferts',
  environment: 'live',
  key_type: 'restricted',
  scopes: ['transfers:read', 'transfers:write'],
});
 
console.log(key.key); // affichee une seule fois

$ cof api-keys create --name "Gestion membres" \
    --environment live --key-type restricted \
    --scopes members:read,members:manage --mfa-code 123456

Une clé restreinte (key_type à restricted, préfixe cof_rk_) n'a que les scopes que vous lui accordez. À l'inverse, une clé complète (key_type à full) couvre tous les scopes, ce qui revient à porter le wildcard *. Choisissez le type restreint dès que la clé sort de votre périmètre de confiance, et combinez-le avec une liste de scopes explicite pour rester au plus près du moindre privilège.