#User Roles

scoped.userRoles stores direct role assignments for host user IDs. It distinguishes incremental assignment from full replacement and can read direct or effective role sets.

#Purpose and preconditions

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#What Do You Want To Do

#Signatures

The signatures below are the public contract. The code block is kept executable-looking so TypeScript users can compare argument order, option requirements, and raw return wrappers quickly.

assign(userId: string, roleId: string, options?: MutationOptions): Promise<MutationResult<UserRoleBindingSet>>
revoke(userId: string, roleId: string, options?: MutationOptions): Promise<MutationResult<UserRoleBindingSet>>
set(userId: string, roleIds: readonly string[], options: RequiredRevisionOptions): Promise<MutationResult<UserRoleBindingSet>>
clear(userId: string, options: RequiredRevisionOptions): Promise<MutationResult<UserRoleBindingSet>>
getDirect(userId: string): Promise<VersionedResult<UserRoleBindingSet>>
getEffective(userId: string): Promise<VersionedResult<UserEffectiveRoles>>
listUsersByRole(roleId: string, query?: CursorQuery): Promise<PageResult<UserRoleBindingSet>>

#Parameters and Returned Fields

Use this section to distinguish host-owned user IDs from permission-core role bindings, direct values, effective values, revisions, and cursor fields.

#Method Details

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#assign(userId, roleId, options?)

• Purpose: Add one role binding to a user without replacing other direct role bindings.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#revoke(userId, roleId, options?)

• Purpose: Remove one direct role binding from a user while preserving the rest.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#set(userId, roleIds, options)

• Purpose: Replace a user's direct role bindings with the provided complete role list.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#clear(userId, options)

• Purpose: Remove all direct roles from a user after checking the expected revision.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#getDirect(userId)

• Purpose: Read the roles directly assigned to a user and their binding revision.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#getEffective(userId)

• Purpose: Read the user's final effective roles after role inheritance and disabled-role filtering.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#listUsersByRole(roleId, query?)

• Purpose: Page through users that directly hold a role, useful for impact review and administration.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: PageResult<T> or the documented paged business result. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#How to Choose assign and set

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#Responses and side effects

Side effects are scoped and revisioned. Writes record audit evidence and invalidate affected semantic cache keys; reads preserve bounded detail metadata so callers can tell whether diagnostics were complete.

{
  "data": {
    "userId": "u-1",
    "roleIds": ["order-reader", "operator"],
    "revision": 2,
    "persisted": true
  },
  "revision": 2,
  "operationId": "operation_...",
  "auditId": "audit_..."
}

#Failures and limits

Failures close authorization instead of widening it. Important limits are enforced before state is committed, and stale previews or revisions must be refreshed rather than guessed.

#Example

The example keeps one narrow path per page. It shows the raw method family and a compact response shape, while the full runnable scenarios live in the examples section.

await scoped.userRoles.assign('u-1', 'order-reader');
const before = await scoped.userRoles.getDirect('u-1');
const replaced = await scoped.userRoles.set('u-1', ['operator'], {
  expectedRevision: before.data.revision,
});

{
  "before": ["order-reader"],
  "after": ["operator"]
}

#Related

Continue with the linked guide or neighboring API page when you need workflow context rather than only signatures.

Continue with Menus.