Skip to content

Controlling app reach (grants)

An external app gets access through a registration document. A grant on that document bounds what the app may attempt at all. The role it signs in with — elected on the consent screen, or pinned for a backend app — bounds what it may see and change. The two bounds apply together on every request.

  • You register an app and must keep its reach narrow.
  • An app needs more or less access than it has.
  • You must switch an app off quickly.
  • The right. You need update rights on app.App documents. The seeded admin and editor roles hold them.
  • The model. Read Apps, grants and roles for the model behind this page.

Open Configure → Apps and start the wizard. Pick a preset: a web app you host signs in through the browser; a backend app signs in with an API key. The setup step collects the name, the sign-in origins, and the redirect addresses.

The permissions step — or the Grants tab on an existing app — lists every doctype by domain. Set one access level per doctype:

Level Grant actions
None no entry
Read read
Write read + write — write covers create and update
Full read + write + delete

Named actions that the doctype declares appear as extra toggles once the level is above None. A child doctype inherits its parent’s level in the editor; the save writes an explicit entry for it.

A backend app acts through a machine identity. Pick its single role on the permissions step. The editor warns when the role misses a required grant action, for example missing: update on fin.Invoice. The warning does not block the save; the real check runs on every request. The role must list api in its connectivity channels, or key issuance refuses.

Publish sets the app status to active. A web app gets its client id and signs in through the consent screen. A backend app issues one API key; the raw key shows once.

Edit the grants on the Grants tab, or set the app to disabled. Facet re-reads the app document on every request, so a change applies on the next request. Nothing needs re-issuing.

The grant is the ceiling: it names the doctype paths and actions the app may attempt. The role decides what exists to grant: Facet keeps only the actions that the role also gives. Row scopes on the role still apply unchanged inside the granted paths. A grant never widens a row filter.

Every read, write, and action entry point runs the grant pre-check first. A combination of domain, path, and action that no grant names is refused. An app with an empty grant set is refused everywhere — this fails closed.

The effective scope is re-resolved per request

Section titled “The effective scope is re-resolved per request”

The token never carries the grant. Facet reloads the app document and re-resolves the intersection on every request. Tighten a grant, and the next request runs under the tighter bound.

The effective scope lists concrete doctype paths only. A wildcard role line collapses onto each granted doctype. A doctype that no grant names answers the same denials that a role without read gives. For example, an app token cannot read core.DocType unless a grant names it.

  • An app token (typ: "app") rides the OAuth authorization code flow with PKCE and DPoP. The consent screen is always shown, and the signing account elects exactly one role for the app.
  • An app-owned API key (the app_api_key channel) authenticates the app’s service account. Verification also checks the app: a key for a draft or disabled app answers the uniform 401. The effective right is grant ∩ pinned role, computed per request.

Every app-channel mutation records the app id, and the audit list filters by it. Login events carry the app id for app sessions. Denials at the pre-check land in the login-event log — see Auditing activity.

This grant set on an app document lets the app read and write contacts, and read deals:

{
"grants": [
{
"target": "crm.Contact",
"actions": [
{ "name": "read", "required": true },
{ "name": "write", "required": true }
]
},
{
"target": "crm.Deal",
"actions": [
{ "name": "read", "required": true },
{ "name": "write", "required": false }
]
}
]
}

required: true means the role must grant the action, or the role is unusable for the app. required: false means Facet includes the action only when the role grants it. Its absence never rejects the role.

The service role no longer covers every required action. The server log names the missing actions, for example update on fin.Invoice. Widen the role or lower the requirement.

A call answers 403 for a doctype the app used to reach

Section titled “A call answers 403 for a doctype the app used to reach”

The grant was narrowed or removed. The next request applies the change.

Grant read on core.DocType, or hardcode the values in the app.

A required grant action is missing on the elected role. Check the warning on the app’s Grants tab.