Web Component Permissions

The declared-permission vocabulary for third-party web components — every scope, what it forwards, and how it maps to project roles

web-componentspermissionssecurity

A web component declares at registration time which data it wants. End users see these scopes in the consent overlay before any third-party code runs, and the platform forwards only data covered by a declared scope — nothing else ever crosses into the sandbox. Grants are resolved server-side, deny-by-default: the component can never widen its own access.

Scope vocabulary

Scope Forwards Notes
user-profile:read The requesting user's { id, email, displayName } under the userProfile data key Never other users' data; anonymous visitors yield no profile
collection:{configurationProperty}:read The documents of the bound datatype, under the {configurationProperty} data key Granted only when the viewing user holds the mapped read permission
collection:{configurationProperty}:create Nothing (grant only) Reserved for write flows; no documents are pushed
collection:{configurationProperty}:update Nothing (grant only) Reserved for write flows; no documents are pushed
collection:{configurationProperty}:delete Nothing (grant only) Reserved for write flows; no documents are pushed

{configurationProperty} is an identifier path (letters, digits, _, $, dot notation for nesting) — for example orders or settings.contactTypeId.

Collection scopes bind at placement time

As a component author you know neither the customer's project nor its datatypes. A collection scope therefore names a property of your component's widget configuration, not a datatype: when an editor places your component, they bind that configuration property to a concrete datatype of their project. The platform then maps the scope onto its regular row-level-security permission for that datatype — the component receives documents only if the viewing user could already read them in the platform itself.

Declaring a datatype configuration property without a matching collection: scope grants no data access.

Reading granted data with the SDK

const { grantedScopes } = await client.whenInitialized();

const profile = client.getUserProfile();      // undefined unless user-profile:read granted
const orders = client.getCollection("orders"); // undefined unless collection:orders:read granted and bound

Design for the denied state: a scope the user's role does not cover is simply absent from grantedScopes, and the matching accessor returns undefined. The framework samples in the starter repository all render an explicit "permission not granted" state.

Markdown | llm.txt