Gate your UI with the manifest
Every credential that can call the API can also read what it may attempt. The permission manifest on
GET /Api/iam/me lists the doctype paths, the actions, and the row scopes the credential reaches. Use
it to hide buttons and to size affordances. The manifest is advisory: the server re-checks every
request and never reads the manifest back.
For agents: Endpoint:
GET /Api/iam/me— returnspermissions(map of"domain.Doctype"keys to action lists),scopes(doctype → action → scope aliases),connectivity, andassistant({access, token_budget, name}). SDK:await facet.whoami()(cached) →await facet.can('delete', 'crm.Company')answers'all' | 'scoped' | 'denied';await facet.scopes('update', 'crm.Company')reads the aliases;await facet.refreshRights()after a role switch or a grant change. Reserved keys"*.*","{domain}.*", and"*.*.except.<action>"are matcher input, not doctypes.
When to use this
Section titled “When to use this”Use the manifest when:
- You hide buttons or menu entries the caller cannot use.
- You show a limit hint when row scopes narrow an action.
- You adapt your app to the channels and the assistant the role allows.
Before you start
Section titled “Before you start”- A credential that calls the API: a session token, an OAuth app token, or a static
fct_key. All three read the manifest. - The reach model behind the manifest: Apps, grants and roles.
- How apps receive that reach: How apps work on Facet.
1. Read the manifest
Section titled “1. Read the manifest”Call the endpoint with your credential. A static key rides the bearer scheme:
curl -s https://facet.example.com/Api/iam/me \ -H "Authorization: Bearer $FACET_API_KEY"An app token rides the DPoP scheme with a proof on every call — see DPoP token binding. The response carries four fields beyond the account profile:
| Field | Content |
|---|---|
permissions |
A map of "domain.Doctype" keys to action lists. |
scopes |
A map of doctype to action to scope aliases. [] means unrestricted. |
connectivity |
The active role’s channels: mcp, webhook, api, assistant. |
assistant |
{access, token_budget, name} — the chat gate, the budget (null = unlimited), and the display name. |
2. Recognise the key forms
Section titled “2. Recognise the key forms”The permissions map folds the role’s permission lines. These rules produce every key:
- A concrete line on
crm.Companylands under the literal key"crm.Company". - A domain-wide line on
hrlands under the domain-wildcard key"hr.*". - A wildcard line keeps its action list on the literal
"*.*". - A wildcard line with carve-outs folds them per action under
"*.*.except.<action>", for example"*.*.except.create". The value lists the subtracted paths. - A key appears only when its fold is non-empty. A doctype key never contains
*.
The scopes map mirrors the row rules. scopes["crm.Company"]["update"] is [] when the update
right is unrestricted, or an alias list such as ["mine"] when row scopes apply. Wildcard lines fold
under the "*.*" scopes key; domain-wide lines fold under the "{domain}.*" key.
This manifest comes from an editor-like role. It reads and creates everywhere, cannot create system
settings, and updates and deletes companies. A domain-wide line adds read on hr, scoped to the
team alias:
{ "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. Match a key in the right order
Section titled “3. Match a key in the right order”If you write your own matcher, grant in this order and stop at the first hit:
- Admin short-circuit: the
"*.*"key with actions["*"]grants everything. - Exact key:
"crm.Company"grantscrm.Company. A key also reaches its descendants —"crm.Contact"reachescrm.Contact.Comment. - Domain-wildcard key:
"hr.*"grants every doctype in the domain. Carve-outs never suppress it. - Wildcard fallback: the
"*.*"action list grants the path. But a"*.*.except.<action>"entry for the checked action subtracts it when it equals or prefix-matches the path. An entry oncore.DocTypealso excludescore.DocType.Comment. An explicit key grant is never suppressed.
Read the scope aliases at the key that granted the action: the doctype key behind an exact hit,
scopes["{domain}.*"] behind a domain-wide grant, and scopes["*.*"] behind the fallback.
4. Use the SDK helpers
Section titled “4. Use the SDK helpers”The SDK matches both manifest shapes for you:
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 — cached after the first call
facet.can('read', 'crm.Company'); // Promise<'all' | 'scoped' | 'denied'>facet.scopes('update', 'crm.Company'); // Promise<string[]> — [] means unrestrictedawait facet.refreshRights(); // re-fetch after a role switch or a grant change'all' is unrestricted. 'scoped' means the action exists but row scopes apply at the server — read
the aliases with scopes. 'denied' means no manifest key reaches the path.
5. App-scoped callers read the effective manifest
Section titled “5. App-scoped callers read the effective manifest”An app token or an app-owned key reads the resolved intersection of grant and role, not the role’s own manifest:
-
Keys are the concrete doctypes the grant names, plus the domain-wildcard form when a wildcard grant target collapses with a wildcard role permission.
-
There is no
"*.*"fallback. -
A carved-out doctype does not appear at all. The fold that covers its own path removes the action.
-
A residual carve-out on descendants appears under the reserved
"crm.Company.except.update"key form, for the matcher to subtract.The SDK helpers match this shape too. From the app’s perspective, a document its grant does not name does not exist. See How apps work on Facet for the grant and role model.
Example
Section titled “Example”This example sizes a toolbar from the manifest. It removes the toolbar when the read right is denied, hides the delete button when the delete right is denied, and shows a hint when the update right is scoped:
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 });
// On the redirect route, after sign-in:await auth.handleCallback(location.href);
await facet.whoami(); // load and cache the manifest
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.';}Against the manifest in step 2, this keeps the toolbar visible (the wildcard fallback grants read),
keeps the delete button (the exact key grants delete), and shows the hint (the update right carries
the mine alias).
Troubleshooting
Section titled “Troubleshooting”The affordance shows, but the call answers 403.
The manifest is advisory; the server denies. The reach moved — call await facet.refreshRights()
and re-render.
A button is missing although the role grants the action.
A wildcard carve-out covers the path, or the manifest is stale. Check the
"*.*.except.<action>" keys and call refreshRights.
*.* is missing for an app token.
The effective manifest never carries the wildcard fallback. That is correct — the grant is the ceiling.
An iteration over the manifest keys renders reserved keys.
Never iterate either map to render one doctype. The reserved "*.*", "{domain}.*", and
"*.*.except.create" keys are not doctypes. Render from the doctype definitions instead.
Related
Section titled “Related”- How apps work on Facet — the grant and role model behind the effective manifest.
- The TypeScript SDK (
@facetapp/sdk) — the client that shipswhoami,can, andscopes. - Roles and permission lines — the line grammar the manifest folds.
- Row scopes (
$self,$mine, named scopes) — what the scope aliases mean. - Apps, grants and roles — the concept.
- Internals on GitHub: doc/backend/iam.md.