Role
`roles.list`, `get`, `create`, `update`, `delete` a `listPermissions`.
Všechny metody
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 obsahuje šest položek, ne tři: emails:send s sebou nese emails:read, threads:write nese threads:read a labels:write nese labels:read. Seznam si přečtěte zpět, místo abyste ho předpokládali.
Role říká, co někdo smí DĚLAT. Se kterými ADRESAMI to smí dělat, je druhá osa a bydlí v openemail.members. Podívejte se tam na grantAddress a revokeAddress. „Smí posílat poštu“ a „smí posílat jako invoices@“ jsou různé věty a workspace, který najme druhého agenta podpory, mění tu druhou, aniž by sáhl na první.
Větvěte podle editable a deletable, ne podle názvu v builtin. Obě jsou false jedině u vlastníka, jehož seznam zní „každé oprávnění, včetně těch vymyšlených příští rok“ a počítá se, místo aby se ukládal; každá jiná role odpovídá na obojí true, včetně pěti, kterými je workspace osazen. Role, kterou někdo přejmenoval, stále odpovídá na obojí správně, jen její název už nevypovídá o ničem.
update seznam oprávnění NAHRAZUJE. Volání pro udělení jediného oprávnění neexistuje, takže roli načtěte, změňte položku, kterou jste měli na mysli, a pošlete zpět všechny. Když pošlete jedno oprávnění, zůstane roli přesně ono jedno plus to, co z něj vyplývá.
delete vyžaduje reassignTo ve chvíli, kdy roli někdo drží, a cestuje jako query parametr, protože tělo u DELETE několik runtimů a řada proxy zahazuje. Výsledek hlásí reassigned a keysReassigned zvlášť, takže skript může logovat, co skutečně udělal, a ne to, oč požádal.
listPermissions() je GET /roles/permissions, pevná cesta sedící přesně tam, kam by šlo id role. Klient ji má napevno, místo aby ten řetězec protáhl přes get, takže dotaz na roli skutečně pojmenovanou „permissions“ je dotazem na roli a vrátí 404, což je poctivá odpověď na to, co bylo napsáno. scope: false označuje položky, které žádný klíč nikdy držet nemůže.
Role je strop klíče
Klíč vydaný pod nějakou rolí smí to, co je PRŮNIKEM jeho vlastních scopes s oprávněními té role, a vyhodnocuje se to na hranici při každém požadavku. Zúžení role tedy odebírá práva jejím klíčům okamžitě, aniž by se kterýkoli z nich rotoval, a klíč bez role nemá žádný strop – null role je proto nejširší stav, v jakém klíč může být, ne nejužší.
Proto také roles.delete trvá na tom, kam klíče přesunout. Osiřelé klíče by přišly o strop úplně, čímž by se tiše povýšily všechny přihlašovací údaje, které role zastropovala.
GET /keys/self a GET /ping hlásí vedle efektivních scopes i roleId a grantedScopes, a přesně tak se odpovídá na „můj klíč má emails:send a dostávám insufficient_scope“: cokoli je v grantedScopes a chybí ve scopes, vzala role. openemail.me.get() a openemail.me.ping() vracejí obojí, otypované.
Parametry
namestringpovinné- Jak workspace roli říká: 1 až 48 znaků, před uložením oříznuto. Názvy jsou v rámci workspace jedinečné bez ohledu na velikost písmen, takže druhý „Support“ je odmítnut chybou `role_name_taken` (409), místo aby vznikl vedle prvního.
descriptionstring- Věta říkající, k čemu role je, oříznutá a nejvýše 240 znaků. Řetězec, který je po oříznutí prázdný, se uloží jako null, takže popis složený z mezer se vrátí jako null, a ne jako to, co jste poslali.
permissionsPermission[]povinné- Co role uděluje, ze slovníku, který servíruje `listPermissions()`; řetězec, který v něm není, je 422 na `permissions`, místo aby se tiše zahodil, takže překlep je ohlášen a nestojí vás celé odpoledne. Seznam se cestou dovnitř ROZŠIŘUJE (`templates:write` uloží vedle sebe i `templates:read`), deduplikuje a srovná zpět do kanonického pořadí, takže uložený seznam si načtěte z odpovědi, místo abyste předpokládali, že je to ten, který jste poslali.
Odpověď
object'role'- Vždy `role`. Náhrobek po smazání odpovídá stejnou hodnotou, `id` role, `deleted: true` a dvěma počty přeřazení, a žádným z ostatních polí níže.
idstring- Id role. Je to to, co jmenuje `roleId` u člena, na co míří strop API klíče a co bere `reassignTo`, když se tato role maže.
namestring- Název role v rámci workspace, oříznutý a jedinečný bez ohledu na velikost písmen. Přejmenovat lze každou roli kromě vlastníkovy, osazené včetně (`builtin` říká, odkud řádek pochází, ne jak se musí dál jmenovat), takže nečtěte „Admin“ jako slib o tom, co role drží. Název, na který už slyší jiná role, je `role_name_taken` (409, `param: "name"`); přejmenování vlastníka je `role_immutable` (409), stejně jako každá jiná jeho úprava.
descriptionstring | null- Věta popisující roli, nebo null, když žádná nebyla zadána. Prázdný vstup se při create i update ukládá jako null, takže tohle nikdy není prázdný řetězec.
permissionsPermission[]- Vše, co role uděluje, už rozšířené a v kanonickém pořadí, ne v tom, v jakém to kdo napsal. To pořadí je nosné: dvě role se stejnými oprávněními si jsou jako JSON rovny, což obrazovce nastavení umožňuje je porovnat a rozhodnout, zda je tlačítko Uložit aktivní.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Ze které ze šesti osazených rolí tento řádek pochází, nebo null u role, kterou si workspace napsal sám. Zaznamenává původ osazení, ne stav: osazená role se přejmenovává, mění oprávnění a maže jako každá jiná. Větvěte podle `editable` a `deletable`, ne podle tohoto pole. Role, které někdo říká „Admin“, nemusí být ta osazená, a ta osazená už se tak jmenovat nemusí.
editableboolean- Počítá se jako `builtin !== 'owner'`, takže je false jedině u role vlastníka a každý PATCH této role je odmítnut chybou `role_immutable` (409). Každá jiná role je upravitelná v plném rozsahu (název, popis i oprávnění), včetně pěti, kterými je workspace osazen.
deletableboolean- Počítá se jako `builtin !== 'owner'`: false jedině u role vlastníka, která se vrací s `role_undeletable` (409), a true u každé jiné role včetně osazených. Ověřte to dřív, než tlačítko nabídnete, ne až po odmítnutí – a role, kterou ještě někdo drží, navíc potřebuje `reassignTo`, jinak je smazání `role_in_use` (409).
membersnumber- Kolik lidí tuto roli drží, spočítáno z řádků členů workspace. Vlastník mezi nimi není: nemá řádek člena a nelze mu roli přidělit, takže role Owner hlásí nula držitelů, i když ho seznam členů ukazuje.
apiKeysnumber- Kolik živých API klíčů tato role zastropovává; odvolané klíče se do počtu nezahrnují, přestože smazání přesměruje každý řádek klíče mířící na tuto roli, odvolané včetně. Je to druhá populace, kterou je třeba přesunout, než role může zmizet, a ta, které si nikdo nevšimne: klíče jsou programy a program si nestěžuje.
createdAtstring- Kdy byl řádek role zapsán, ISO-8601. Vestavěné řádky se osazují líně, teprve když je něco poprvé potřebuje – čtení seznamu rolí, vytvoření role nebo obrazovka API klíčů – a ne při vzniku workspace, takže časové razítko vestavěné role říká, kdy dorazil ten první požadavek, ne kdy workspace vznikl.
updatedAtstring- Kdy se role naposledy změnila, ISO-8601. Posune ji každý přijatý PATCH, i takový, který nastaví pole na hodnotu, kterou už mělo.