Block SDK · Guides
Users and role permissions
Read the active collaborator profile with useOrbixUser and gate block actions by role with useBlockPermissions and PermissionGuard.
Blocks can inspect who is currently viewing the document, list active collaborators, and restrict administrative or destructive controls inside the block UI by role.
Reading user and collaborator identity (useOrbixUser)
useOrbixUser() returns the active collaborator profile along with the document's collaborator roster:
user.id,user.name,user.email,user.avatarUrl,user.role— active viewer identity.user.collaborators(aliasuser.members) — array ofOrbixCollaboratorProfileentries in the current document or workspace.user.authenticatedUser— the underlying signed-in account, preserved even when previewing another collaborator's perspective.user.switchPerspective(memberIdOrKey)/user.resetPerspective()— preview howpersonalstate renders for another member during development.
Role-based UI gating (useBlockPermissions and <PermissionGuard>)
RolePermissionEngine defines five default roles in descending precedence:
| Role ID | Default permissions |
|---|---|
'creator' | ADMINISTRATOR, MANAGE_BLOCK, MANAGE_ROLES, MANAGE_SECRETS, EDIT_CONTENT, INTERACT, VIEW_CONTENT, VIEW_ANALYTICS, EXPORT_DATA, TRIGGER_WEBHOOK |
'admin' | MANAGE_BLOCK, MANAGE_ROLES, EDIT_CONTENT, INTERACT, VIEW_CONTENT, VIEW_ANALYTICS, EXPORT_DATA, TRIGGER_WEBHOOK |
'editor' | EDIT_CONTENT, INTERACT, VIEW_CONTENT, VIEW_ANALYTICS, EXPORT_DATA |
'member' (default) | INTERACT, VIEW_CONTENT |
'guest' | VIEW_CONTENT |
Use useBlockPermissions(props) in event handlers and <PermissionGuard> around conditional UI controls:
import {
defineBlock,
PermissionGuard,
useBlockPermissions,
useOrbixState,
useOrbixUser,
type BlockRenderProps,
} from '@orbixdocs/sdk';
interface ReleaseState {
approvedBy: string | null;
}
export default defineBlock({
manifest: {
id: 'acme.release-gate',
name: 'Release Gate',
version: '1.0.0',
sdk: '^3.0.0',
},
component(props: BlockRenderProps) {
const user = useOrbixUser();
const { currentRole, hasPermission, isReadOnly } = useBlockPermissions(props);
const [state, setState] = useOrbixState<ReleaseState>(props, {
approvedBy: null,
});
return (
<div
style={{
padding: 14,
borderRadius: 12,
background: 'var(--orbix-card-bg, #16171b)',
border: '1px solid var(--orbix-surface-border, #2a2b32)',
color: 'var(--orbix-text-primary, #f4f4f5)',
}}
>
<div style={{ fontSize: 13, marginBottom: 8 }}>
Signed in as <strong>{user.name}</strong> ({currentRole.name})
</div>
<div style={{ marginBottom: 10 }}>
Status:{' '}
{state.approvedBy
? `Approved by ${state.approvedBy}`
: 'Awaiting approval'}
</div>
<PermissionGuard
props={props}
permission="EDIT_CONTENT"
fallback={
<span style={{ fontSize: 12, color: 'var(--orbix-text-secondary, #a1a1aa)' }}>
Editor or Admin role required to change approval state.
</span>
}
>
<div style={{ display: 'flex', gap: 8 }}>
<button
type="button"
disabled={isReadOnly}
onClick={() => setState({ approvedBy: user.name })}
>
Approve release
</button>
{hasPermission('MANAGE_BLOCK') && state.approvedBy && (
<button
type="button"
disabled={isReadOnly}
onClick={() => setState({ approvedBy: null })}
>
Reset
</button>
)}
</div>
</PermissionGuard>
</div>
);
},
});How role checks interact with read-only documents
- Read-only override: When a document is opened in read-only mode (
props.isReadOnly === true),useBlockPermissionsautomatically setsisHostandisAdmintofalseand restrictshasPermission(...)to'VIEW_CONTENT'only, regardless of the user's assigned role. - UI gating vs. host enforcement:
PermissionGuardandRolePermissionEnginecontrol role visibility inside your block's client UI. Host-enforced security boundaries (cross-site iframe isolation,teamstate write blocking on read-only pages, domain allowlists, and Vault secret sealing) are enforced independently by the Orbix host; see Sandbox and isolation and Permissions and capabilities. - Testing roles in Block Studio: Call
simulateRole('guest')(andsimulateRole(null)to reset) during local development to verify fallback states without signing into a second account.