Dimensionner l’UI avec le manifeste
Tout appelant de l’API peut aussi lire ce qu’il a le droit de tenter. Le
manifeste de permissions de GET /Api/iam/me liste les chemins de doctypes,
les actions et les périmètres de lignes que l’appelant atteint. Utilisez-le
pour cacher des boutons et pour dimensionner l’interface. Le manifeste n’a
qu’une valeur indicativeà : le serveur revérifie chaque requête et ne relit
jamais le manifeste.
Pour les agentsà : point de terminaison :
GET /Api/iam/me— renvoiepermissions(une map des clés"domain.Doctype"vers des listes d’actions),scopes(doctype → action → alias de périmètres),connectivityetassistant({access, token_budget, name}). SDKà:await facet.whoami()(en cache) →await facet.can('delete', 'crm.Company')répond'all' | 'scoped' | 'denied';await facet.scopes('update', 'crm.Company')lit les aliasà ;await facet.refreshRights()après un changement de rôle ou d’attribution. Les clés réservées"*.*","{domain}.*"et"*.*.except.<action>"sont une entrée du matcher, pas des doctypes.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Utilisez le manifeste quandà :
- vous cachez des boutons ou des entrées de menu que l’appelant ne peut pas utiliser,
- vous affichez une indication de limite quand des périmètres de lignes restreignent une action,
- vous adaptez votre app aux canaux et à l’assistant que le rôle permet.
Avant de commencer
Section intitulée « Avant de commencer »- Un moyen de s’authentifier auprès de l’APIà: un token de session, un token
d’app OAuth, ou une clé
fct_statique. Les trois lisent le manifeste. - Le modèle de portée qui sous-tend le manifesteà : Appsà : attributions ∩ rôles.
- Comment les apps reçoivent cette portéeà : Le fonctionnement des apps sur Facet.
1. Lire le manifeste
Section intitulée « 1. Lire le manifeste »Appelez le point de terminaison avec votre moyen d’authentification. Une clé statique emprunte le schéma bearerà :
curl -s https://facet.example.com/Api/iam/me \ -H "Authorization: Bearer $FACET_API_KEY"Un token d’app emprunte le schéma DPoP avec une preuve à chaque appel — voir Liaison de token DPoP. La réponse porte quatre champs en plus du profil du compteà :
| Champ | Contenu |
|---|---|
permissions |
Une map des clés "domain.Doctype" vers des listes d’actions. |
scopes |
Une map du doctype vers l’action vers les alias de périmètres. [] signifie sans restriction. |
connectivity |
Les canaux du rôle actifà : mcp, webhook, api, assistant. |
assistant |
{access, token_budget, name} — la porte d’accès au chat, le budget (null = illimité) et le nom d’affichage. |
2. Reconnaître les formes de clés
Section intitulée « 2. Reconnaître les formes de clés »La map permissions regroupe les lignes de permission du rôle. Ces règles
produisent chaque cléà :
- Une ligne concrète sur
crm.Companyatterrit sous la clé littérale"crm.Company". - Une ligne à l’échelle du domaine sur
hratterrit sous la clé joker de domaine"hr.*". - Une ligne joker garde sa liste d’actions sur la clé littérale
"*.*". - Une ligne joker avec des retranchements range ceux-ci par action sous
"*.*.except.<action>", par exemple"*.*.except.create". La valeur liste les chemins soustraits. - Une clé n’apparaît que si son regroupement n’est pas vide. Une clé de
doctype ne contient jamais
*.
La map scopes reflète les règles de lignes.
scopes["crm.Company"]["update"] vaut [] quand le droit de mise à jour est
sans restriction, ou une liste d’alias comme ["mine"] quand des périmètres
de lignes s’appliquent. Les lignes joker se rangent sous la clé "*.*" de
scopes ; les lignes à l’échelle du domaine sous la clé "{domain}.*".
Ce manifeste vient d’un rôle proche d’un éditeur. Il lit et crée partout, ne
peut pas créer de paramètres système, et met à jour et supprime des sociétés.
Une ligne à l’échelle du domaine ajoute la lecture sur hr, limitée à l’alias
team :
{ "permissions": { "*.*": ["create", "read"], "*.*.except.create": ["core.SystemSettings"], "crm.Company": ["update", "delete"], "hr.*": ["read"] }, "scopes": { "*.*": { "create": [], "read": [] }, "crm.Company": { "update": ["mine"], "delete": [] }, "hr.*": { "read": ["team"] } }}3. Associer une clé dans le bon ordre
Section intitulée « 3. Associer une clé dans le bon ordre »Si vous écrivez votre propre matcher, accordez dans cet ordre et arrêtez-vous à la première correspondance :
- Court-circuit admin : la clé
"*.*"avec les actions["*"]donne tout. - Clé exacteà :
"crm.Company"donnecrm.Company. Une clé atteint aussi ses descendants —"crm.Contact"atteintcrm.Contact.Comment. - Clé joker de domaineà :
"hr.*"donne chaque doctype du domaine. Les retranchements ne la suppriment jamais. - Repli jokerà : la liste d’actions de
"*.*"donne le chemin. Mais une entrée"*.*.except.<action>"pour l’action vérifiée la soustrait quand elle est égale au chemin ou lui correspond par préfixe. Une entrée surcore.DocTypeexclut aussicore.DocType.Comment. Ce qu’une clé explicite accorde n’est jamais supprimé.
Lisez les alias de périmètres à la clé qui a donné l’action : la clé de
doctype derrière une correspondance exacte, scopes["{domain}.*"] derrière
une ligne à l’échelle du domaine, et scopes["*.*"] derrière le repli joker.
4. Utiliser les helpers du SDK
Section intitulée « 4. Utiliser les helpers du SDK »Le SDK associe les deux formes de manifeste pour vousà :
import { createFacetClient, oauthBrowser } from '@facetapp/sdk';
const auth = oauthBrowser({ slug: 'crm-console', redirectUri: `${location.origin}/callback` });const facet = createFacetClient({ baseUrl: 'https://facet.example.com', auth });
await facet.whoami(); // GET /Api/iam/me — en cache après le premier appel
facet.can('read', 'crm.Company'); // Promise<'all' | 'scoped' | 'denied'>facet.scopes('update', 'crm.Company'); // Promise<string[]> — [] signifie sans restrictionawait facet.refreshRights(); // re-fetch après un changement de rôle ou d’attribution'all' signifie sans restriction. 'scoped' signifie que l’action existe
mais que des périmètres de lignes s’appliquent côté serveur — lisez les alias
avec scopes. 'denied' signifie qu’aucune clé du manifeste n’atteint le
chemin.
5. Les appelants d’app lisent le manifeste effectif
Section intitulée « 5. Les appelants d’app lisent le manifeste effectif »Un token d’app ou une clé d’app lit l’intersection résolue de l’attribution et du rôle, pas le manifeste propre du rôleà :
- Les clés sont les doctypes concrets que l’attribution nomme, plus la forme joker de domaine quand une cible d’attribution joker se combine avec une permission de rôle joker.
- Il n’y a pas de repli joker
"*.*". - Un doctype retranché n’apparaît pas du tout. Le regroupement qui couvre son propre chemin retire l’action.
- Un retranchement résiduel sur les descendants apparaît sous la forme de clé
réservée
"crm.Company.except.update", pour que le matcher le soustraie.
Les helpers du SDK associent aussi cette forme. Du point de vue de l’app, un document que son attribution ne nomme pas n’existe pas. Voir Le fonctionnement des apps sur Facet pour le modèle attribution et rôle.
Cet exemple dimensionne une barre d’outils d’après le manifeste. Il retire la barre d’outils quand la lecture est refusée, cache le bouton supprimer quand la suppression est refusée, et affiche une indication quand la mise à jour est limitée par des périmètresà :
import { createFacetClient, oauthBrowser } from '@facetapp/sdk';
const auth = oauthBrowser({ slug: 'crm-console', redirectUri: `${location.origin}/callback` });const facet = createFacetClient({ baseUrl: 'https://facet.example.com', auth });
// Sur la route de redirection, après la connexion :await auth.handleCallback(location.href);
await facet.whoami(); // charge et met en cache le manifeste
const toolbar = document.querySelector('#company-toolbar') as HTMLElement;const deleteButton = toolbar.querySelector('#delete-company') as HTMLButtonElement;const hint = toolbar.querySelector('#scope-hint') as HTMLElement;
if ((await facet.can('read', 'crm.Company')) === 'denied') { toolbar.remove();} else { deleteButton.hidden = (await facet.can('delete', 'crm.Company')) === 'denied';
const updateScopes = await facet.scopes('update', 'crm.Company'); hint.hidden = updateScopes.length === 0; if (updateScopes.length > 0) hint.textContent = 'You can change companies you own.';}Contre le manifeste de l’étape 2, ce code garde la barre d’outils visible (le
repli joker donne read), garde le bouton supprimer (la clé exacte donne
delete) et affiche l’indication (le droit de mise à jour porte l’alias
mine).
Dépannage
Section intitulée « Dépannage »L’élément s’affiche, mais l’appel répond 403.
Le manifeste est indicatifà ; le serveur refuse. La portée a changé — appelez
await facet.refreshRights() et refaites le rendu.
Un bouton manque alors que le rôle donne l’action.
Un retranchement joker couvre le chemin, ou le manifeste est périmé. Vérifiez
les clés "*.*.except.<action>" et appelez refreshRights.
*.* est absent pour un token d’app.
Le manifeste effectif ne porte jamais le repli joker. C’est correct — l’attribution est le plafond.
Une itération sur les clés du manifeste rend les clés réservées.
N’iterez jamais l’une des maps pour rendre un doctype. Les clés réservées
"*.*", "{domain}.*" et "*.*.except.create" ne sont pas des doctypes.
Faites le rendu à partir des définitions de doctypes.
Voir aussi
Section intitulée « Voir aussi »- Le fonctionnement des apps sur Facet — le modèle attribution et rôle qui sous-tend le manifeste effectif.
- Le SDK TypeScript (
@facetapp/sdk) — le client qui fournitwhoami,canetscopes. - Rôles et lignes de permission — la grammaire des lignes que le manifeste regroupe.
- Les périmètres de lignes — ce que signifient les alias de périmètres.
- Appsà : attributions ∩ rôles — le concept.
- Internes sur GitHubà : doc/backend/iam.md.