Rôles
`roles.list`, `get`, `create`, `update`, `delete` et `listPermissions`.
Toutes les méthodes
const roles = await openemail.roles.list()const role = await openemail.roles.get('role_…') const support = await openemail.roles.create({ name: 'Support', description: 'Answers the shared inboxes and nothing else.', permissions: ['emails:send', 'threads:write', 'labels:write'],}) console.log(support.permissions) await openemail.roles.update(support.id, { permissions: [...support.permissions, 'templates:read'],}) await openemail.roles.delete(support.id, { reassignTo: 'role_…' }) const vocabulary = await openemail.roles.listPermissions()support.permissions contient six entrées, pas trois : emails:send entraîne emails:read, threads:write entraîne threads:read et labels:write entraîne labels:read. Relisez la liste renvoyée plutôt que de la supposer.
Un rôle dit ce que quelqu'un a le droit de FAIRE. Les ADRESSES sur lesquelles il peut le faire constituent l'autre axe et vivent sur openemail.members ; voyez-y grantAddress et revokeAddress. « Peut envoyer du courrier » et « peut envoyer depuis invoices@ » sont deux phrases différentes, et un espace de travail qui recrute un second agent de support modifie la seconde sans toucher à la première.
Branchez sur editable et deletable plutôt que sur le nom de builtin. Les deux valent false pour le seul rôle propriétaire, dont la liste est « toutes les permissions, y compris celles inventées l'an prochain » et se calcule plutôt qu'elle ne se stocke ; tous les autres rôles répondent true aux deux, y compris les cinq avec lesquels un espace de travail est initialisé. Un rôle que quelqu'un a renommé répond toujours correctement aux deux, et son nom ne vous apprend plus rien.
update REMPLACE la liste des permissions. Il n'existe pas d'appel pour en accorder une seule : lisez le rôle, modifiez l'entrée voulue et renvoyez-les toutes. Envoyer une seule permission laisse le rôle avec exactement celle-là, plus ce qu'elle implique.
delete exige reassignTo dès que quelqu'un détient le rôle, et ce paramètre voyage dans la query string parce qu'un corps sur DELETE est supprimé par plusieurs runtimes et un certain nombre de proxys. Le résultat rapporte reassigned et keysReassigned séparément, afin qu'un script puisse journaliser ce qu'il a fait plutôt que ce qu'il a demandé.
listPermissions() correspond à GET /roles/permissions, un chemin fixe placé exactement là où irait un id de rôle. Le client le code en dur plutôt que de faire passer la chaîne par get : demander un rôle réellement nommé « permissions » demande bien un rôle et obtient un 404, ce qui est la réponse honnête à ce qui a été saisi. scope: false marque les entrées qu'aucune clé ne pourra jamais détenir.
Un rôle est le plafond d'une clé
Une clé émise pour un rôle peut faire ce qu'autorisent ses propres portées INTERSECTÉES avec les permissions de ce rôle, résolues à chaque requête à la frontière. Restreindre un rôle révoque donc ses clés à chaud, sans qu'aucune ne soit rotationnée, et une clé sans rôle n'a aucun plafond : un rôle null est l'état le plus large dans lequel une clé puisse se trouver, pas le plus étroit.
C'est aussi pourquoi roles.delete exige un endroit où déplacer les clés. Les laisser orphelines supprimerait entièrement leur plafond, promouvant en silence chaque identifiant que le rôle limitait.
GET /keys/self et GET /ping rapportent roleId et grantedScopes à côté des scopes effectives, et c'est ainsi que l'on répond à « ma clé a emails:send et je reçois insufficient_scope » : tout ce qui figure dans grantedScopes et manque dans scopes a été retiré par le rôle. openemail.me.get() et openemail.me.ping() renvoient les deux, typés.
Paramètres
namestringobligatoire- Le nom que l'espace de travail donne au rôle : de 1 à 48 caractères, dont les espaces de début et de fin sont supprimés avant stockage. Les noms sont uniques par espace de travail, sans distinction de casse : un second « Support » est refusé avec `role_name_taken` (409) plutôt que créé à côté du premier.
descriptionstring- Une phrase disant à quoi sert le rôle, débarrassée de ses espaces de début et de fin et limitée à 240 caractères. Une chaîne vide une fois ces espaces retirés est stockée comme null : une description faite d'espaces revient donc à null et non telle que vous l'avez envoyée.
permissionsPermission[]obligatoire- Ce que le rôle accorde, pris dans le vocabulaire que sert `listPermissions()` ; une chaîne qui n'en fait pas partie donne un 422 sur `permissions` au lieu d'être silencieusement écartée, si bien qu'une faute de frappe est signalée plutôt que de vous coûter un après-midi. La liste est ÉTENDUE à l'entrée (`templates:write` fait stocker `templates:read` à côté), dédupliquée et remise dans l'ordre canonique : lisez donc la liste stockée dans la réponse plutôt que de supposer que c'est celle que vous avez envoyée.
Réponse
object'role'- Toujours `role`. Le marqueur de suppression répond avec la même valeur, l'`id` du rôle, `deleted: true` et les deux compteurs de réaffectation, et aucun des autres champs ci-dessous.
idstring- L'id du rôle. C'est ce que nomme le `roleId` d'un membre, ce que vise le plafond d'une clé API, et ce que prend `reassignTo` quand ce rôle est supprimé.
namestring- Le nom que l'espace de travail donne au rôle, espaces de début et de fin retirés et unique sans distinction de casse. Tous les rôles sauf celui du propriétaire peuvent être renommés, y compris ceux issus de l'initialisation (`builtin` dit d'où vient une ligne, pas comment elle doit continuer à s'appeler) : ne lisez donc pas « Admin » comme une promesse sur ce que le rôle détient. Un nom auquel un autre rôle répond déjà donne `role_name_taken` (409, `param: "name"`) ; renommer le propriétaire donne `role_immutable` (409), comme toute autre modification de celui-ci.
descriptionstring | null- La phrase décrivant le rôle, ou null si aucune n'a été donnée. Une entrée vide est stockée comme null à la création comme à la mise à jour : ce champ n'est donc jamais une chaîne vide.
permissionsPermission[]- Tout ce que le rôle accorde, déjà étendu et dans l'ordre canonique plutôt que dans celui où on l'a saisi. Cet ordre est structurant : deux rôles détenant les mêmes permissions se comparent comme égaux en JSON, ce qui permet à un écran de paramètres de les comparer pour décider si Enregistrer est actif.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Duquel des six rôles initiaux cette ligne provient, ou null pour un rôle que l'espace de travail a écrit lui-même. Le champ enregistre l'origine et non un statut : un rôle initial se renomme, se repermissionne et se supprime comme n'importe quel autre. Branchez sur `editable` et `deletable` plutôt que sur celui-ci. Un rôle que quelqu'un a appelé « Admin » n'est pas forcément le rôle initial, et le rôle initial peut ne plus porter ce nom.
editableboolean- Calculé comme `builtin !== 'owner'` : il vaut donc false pour le seul rôle propriétaire, et tout PATCH de ce rôle est refusé avec `role_immutable` (409). Tous les autres rôles sont entièrement modifiables (nom, description et permissions), y compris les cinq avec lesquels un espace de travail est initialisé.
deletableboolean- Calculé comme `builtin !== 'owner'` : false pour le seul rôle propriétaire, qui répond `role_undeletable` (409), et true pour tous les autres, y compris ceux issus de l'initialisation. Vérifiez-le avant de proposer le bouton plutôt qu'après le refus ; un rôle que quelqu'un détient encore exige en outre `reassignTo`, sans quoi la suppression donne `role_in_use` (409).
membersnumber- Combien de personnes détiennent ce rôle, compté à partir des lignes de membres de l'espace de travail. Le propriétaire n'en fait pas partie : il n'a pas de ligne de membre et ne peut pas recevoir de rôle, si bien que le rôle Owner affiche zéro détenteur alors même que la liste des membres l'affiche.
apiKeysnumber- Combien de clés API actives sont plafonnées par ce rôle ; les clés révoquées sont exclues du compte, même si une suppression re-pointe toutes les lignes de clé visant le rôle, révoquées comprises. C'est la seconde population à déplacer avant que le rôle puisse disparaître, et celle que personne ne remarque : les clés sont des programmes, et un programme ne se plaint pas.
createdAtstring- Date d'écriture de la ligne du rôle, au format ISO-8601. Les lignes intégrées sont créées paresseusement la première fois que quelque chose en a besoin — lecture de la liste des rôles, création d'un rôle ou écran des clés API — et non à la création de l'espace de travail : l'horodatage d'un rôle intégré correspond donc au moment où cette première requête est arrivée, et non à la création de l'espace de travail.
updatedAtstring- Date du dernier changement du rôle, au format ISO-8601. Chaque PATCH accepté la fait avancer, y compris celui qui affecte à un champ la valeur qu'il détenait déjà.