Rols
`roles.list`, `get`, `create`, `update`, `delete` i `listPermissions`.
Tots els mètodes
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 conté sis entrades, no pas tres: emails:send arrossega emails:read, threads:write arrossega threads:read i labels:write arrossega labels:read. Torna a llegir la llista en lloc de donar-la per suposada.
Un rol diu què pot FER algú. A quines ADRECES ho pot fer és l'altre eix i viu a openemail.members. Hi trobaràs grantAddress i revokeAddress. «Pot enviar correu» i «pot enviar com a invoices@» són frases diferents, i un workspace que contracta un segon agent de suport canvia la segona sense tocar la primera.
Ramifica segons editable i deletable i no segons el nom de builtin. Tots dos són false només per al propietari, la llista del qual és «tots els permisos, inclosos els que s'inventin l'any que ve» i es calcula en lloc d'emmagatzemar-se; qualsevol altre rol respon true als dos, inclosos els cinc amb què s'inicialitza un workspace. Un rol que algú ha reanomenat continua responent correctament a tots dos, i el seu nom ja no et diu res.
update SUBSTITUEIX la llista de permisos. No hi ha cap crida per concedir-ne un de sol, així que llegeix el rol, canvia l'entrada que volies i torna-los a enviar tots. Enviar un sol permís deixa el rol amb exactament aquell, més el que impliqui.
delete necessita reassignTo tan bon punt algú té el rol, i viatja com a paràmetre de consulta perquè diversos entorns d'execució i uns quants proxies descarten el cos d'un DELETE. El resultat informa de reassigned i keysReassigned per separat, de manera que un script pot registrar el que va fer i no el que va demanar.
listPermissions() és GET /roles/permissions, una ruta fixa situada exactament on aniria l'id d'un rol. El client la codifica literalment en lloc de passar la cadena per get, de manera que demanar un rol que realment es digui «permissions» demana un rol i rep un 404, que és la resposta honesta al que s'ha escrit. scope: false marca les entrades que cap clau pot tenir mai.
Un rol és el sostre d'una clau
Una clau emesa contra un rol pot fer els seus propis scopes INTERSECATS amb els permisos d'aquell rol, resolts per petició al límit. Per tant, restringir un rol revoca les seves claus en viu, sense que se'n roti cap, i una clau sense rol no té cap sostre, cosa que fa que un rol null sigui l'estat més ampli en què pot estar una clau, no pas el més estret.
Aquest és també el motiu pel qual roles.delete insisteix a tenir un lloc on moure les claus. Deixar-les òrfenes eliminaria completament el seu sostre i promocionaria en silenci totes les credencials que el rol limitava.
GET /keys/self i GET /ping informen de roleId i grantedScopes al costat dels scopes efectius, que és com es respon a «la meva clau té emails:send i rebo insufficient_scope»: tot el que hi ha a grantedScopes i falta a scopes l'ha tret el rol. openemail.me.get() i openemail.me.ping() retornen tots dos, tipats.
Paràmetres
namestringobligatori- Com anomena el workspace el rol: d'1 a 48 caràcters, retallats abans de desar-se. Els noms són únics per workspace sense distingir majúscules i minúscules, de manera que un segon «Support» es rebutja amb `role_name_taken` (409) en lloc de crear-se al costat del primer.
descriptionstring- Una frase que diu per a què serveix el rol, retallada i de 240 caràcters com a màxim. Una cadena que queda buida un cop retallada es desa com a null, de manera que una descripció feta d'espais torna com a null i no com el que vas enviar.
permissionsPermission[]obligatori- El que concedeix el rol, extret del vocabulari que serveix `listPermissions()`; una cadena que no hi és dona un 422 a `permissions` en lloc de descartar-se en silenci, així que una errada tipogràfica s'informa en comptes de costar-te una tarda. La llista s'EXPANDEIX a l'entrada (`templates:write` desa `templates:read` al seu costat), es deduplica i es torna a posar en ordre canònic, així que llegeix la llista desada de la resposta en lloc de suposar que és la que vas enviar.
Resposta
object'role'- Sempre `role`. La làpida d'eliminació respon amb el mateix valor, l'`id` del rol, `deleted: true` i els dos recomptes de reassignació, i cap dels altres camps de sota.
idstring- L'id del rol. És el que anomena el `roleId` d'un membre, allò a què apunta el sostre d'una clau API, i el que accepta `reassignTo` quan s'elimina aquest rol.
namestring- El nom que el workspace dona al rol, retallat i únic sense distingir majúscules i minúscules. Tots els rols excepte el del propietari es poden reanomenar, inclosos els inicialitzats (`builtin` diu d'on ve una fila, no com s'ha de continuar dient), així que no llegeixis «Admin» com una promesa sobre el que conté el rol. Un nom al qual ja respon un altre rol dona `role_name_taken` (409, `param: "name"`); reanomenar el propietari dona `role_immutable` (409), com qualsevol altra edició seva.
descriptionstring | null- La frase que descriu el rol, o null si no se'n va donar cap. Una entrada en blanc es desa com a null tant a create com a update, de manera que això no és mai una cadena buida.
permissionsPermission[]- Tot el que concedeix el rol, ja expandit i en ordre canònic i no en l'ordre en què algú el va escriure. Aquest ordre és estructural: dos rols amb els mateixos permisos es comparen iguals com a JSON, i això és el que permet que una pantalla de configuració els compari per decidir si Desa està activat.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- De quin dels sis rols inicialitzats prové aquesta fila, o null si el workspace la va escriure ell mateix. Registra l'origen i no un estat: un rol inicialitzat es reanomena, se li canvien els permisos i s'elimina com qualsevol altre. Ramifica segons `editable` i `deletable` i no segons això. Un rol que algú ha anomenat «Admin» no té per què ser l'inicialitzat, i l'inicialitzat pot ser que ja no es digui així.
editableboolean- Es calcula com `builtin !== 'owner'`, de manera que només és false per al rol de propietari i tot PATCH d'aquest rol es rebutja amb `role_immutable` (409). Qualsevol altre rol és editable del tot (nom, descripció i permisos), inclosos els cinc amb què s'inicialitza un workspace.
deletableboolean- Es calcula com `builtin !== 'owner'`: false només per al rol de propietari, que torna `role_undeletable` (409), i true per a qualsevol altre rol, inclosos els inicialitzats. Comprova-ho abans d'oferir el botó i no després del rebuig, tot i que un rol que algú encara té també necessita `reassignTo`, o l'eliminació dona `role_in_use` (409).
membersnumber- Quantes persones tenen aquest rol, comptades a partir de les files de membres del workspace. El propietari no hi és: no té fila de membre i no se li pot assignar cap rol, de manera que el rol Owner informa de zero titulars encara que la llista de membres el mostri.
apiKeysnumber- Quantes claus API actives estan limitades per aquest rol; les claus revocades queden fora del recompte, tot i que una eliminació reapunta totes les files de clau que apunten al rol, incloses les revocades. És la segona població que cal moure abans que el rol pugui desaparèixer, i la que ningú no nota: les claus són programes, i un programa no es queixa.
createdAtstring- Quan es va escriure la fila del rol, ISO-8601. Les files integrades es creen de manera mandrosa el primer cop que alguna cosa les necessita, com ara una lectura de la llista de rols, la creació d'un rol o la pantalla de claus API, i no en crear el workspace, de manera que la marca de temps d'una integrada és quan va arribar aquella primera petició i no quan es va crear el workspace.
updatedAtstring- Quan va canviar el rol per última vegada, ISO-8601. Cada PATCH acceptat l'actualitza, inclòs un que assigna a un camp el valor que ja tenia.