Skip to Content
OrbixDocs
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 (alias user.members) — array of OrbixCollaboratorProfile entries 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 how personal state renders for another member during development.

Role-based UI gating (useBlockPermissions and <PermissionGuard>)

RolePermissionEngine defines five default roles in descending precedence:

Role IDDefault 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:

src/ReleaseGateBlock.tsx
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), useBlockPermissions automatically sets isHost and isAdmin to false and restricts hasPermission(...) to 'VIEW_CONTENT' only, regardless of the user's assigned role.
  • UI gating vs. host enforcement: PermissionGuard and RolePermissionEngine control role visibility inside your block's client UI. Host-enforced security boundaries (cross-site iframe isolation, team state 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') (and simulateRole(null) to reset) during local development to verify fallback states without signing into a second account.

On this page