Custom Roles

Business Accounts are in early access. See Business Accounts for the model.

A custom role is a name your account defines that inherits a built-in role’s authority: admin or viewer, never owner. A member holding cfo, for example, has exactly what admin grants, but your product can show and reason about the distinct name instead of a generic admin. See Members & roles for the built-in roles a custom role builds on.

Define a role

defineBusinessAccountRole creates a custom role for the account. Owner or admin only.

JavaScript
React

import { defineBusinessAccountRole } from '@dynamic-labs-sdk/client/waas';

await defineBusinessAccountRole({
  businessAccountId: account.id,
  role: 'cfo',
  inherits: 'admin',
});

import { useDefineBusinessAccountRole } from '@dynamic-labs-sdk/react-hooks';

const { mutate } = useDefineBusinessAccountRole();
mutate({ businessAccountId, role: 'cfo', inherits: 'admin' });

A role name is case-insensitive: CFO and cfo name the same role, and the account stores it lowercase. It cannot reuse a built-in name (owner, admin, viewer) or a name another live role in the account already uses.

List roles

listBusinessAccountRoles returns the account’s custom roles, keyed by name.

JavaScript
React

import { listBusinessAccountRoles } from '@dynamic-labs-sdk/client/waas';

const roles = await listBusinessAccountRoles({ businessAccountId: account.id });
// roles.cfo?.inherits === 'admin'

import { useListBusinessAccountRoles } from '@dynamic-labs-sdk/react-hooks';

const RoleList = ({ businessAccountId }: { businessAccountId: string }) => {
  const { data: roles, isLoading } = useListBusinessAccountRoles({ businessAccountId });
  if (isLoading) return null;
  return (
    <ul>
      {Object.entries(roles ?? {}).map(([name, def]) => (
        <li key={name}>{name} (inherits {def.inherits})</li>
      ))}
    </ul>
  );
};

An account with no custom roles returns an empty map. That is an answer, not a missing resource.

Assign a role

A custom role’s name is a valid role value anywhere a built-in role is: addBusinessAccountMember and updateBusinessAccountMemberRole both accept it. See Members & roles for both calls. Assigning a role your account has not defined fails, so define it first.

import { updateBusinessAccountMemberRole } from '@dynamic-labs-sdk/client/waas';

await updateBusinessAccountMemberRole({
  businessAccountId: account.id,
  userId,
  role: 'cfo',
});

Read a member’s custom role

A member’s role on detail.members is always the built-in it inherits, so a cfo holder still reads admin there. The member’s customRole field carries the actual name and what it inherits.

import { getBusinessAccount } from '@dynamic-labs-sdk/client/waas';

const detail = await getBusinessAccount({ businessAccountId: account.id });
const member = detail.members.find((m) => m.userId === userId);
// member.role === 'admin'
// member.customRole === { name: 'cfo', inherits: 'admin' }

customRole is null for a member holding a built-in role directly.

Delete a role

deleteBusinessAccountRole removes the definition. Owner or admin only.

JavaScript
React

import { deleteBusinessAccountRole } from '@dynamic-labs-sdk/client/waas';

await deleteBusinessAccountRole({ businessAccountId: account.id, role: 'cfo' });

import { useDeleteBusinessAccountRole } from '@dynamic-labs-sdk/react-hooks';

const { mutate } = useDeleteBusinessAccountRole();
mutate({ businessAccountId, role: 'cfo' });

Deleting a role does not remove its holders or their authority: each one keeps reading the role’s inherited base (admin or viewer), only the distinct name goes away. Deletion is refused while a governance requirement still names the role. Remove it from governance first.

Governance

Defining and deleting a role are themselves governed actions (Define role, Delete role), and a governance requirement’s eligible approvers or initiators can name a custom role alongside the built-in ones. This requirement asks for one approval from a cfo holder whenever a member is added:

import {
  getBusinessAccountGovernance,
  setBusinessAccountGovernance,
} from '@dynamic-labs-sdk/client/waas';

const businessAccountId = 'ba_123';
const current = await getBusinessAccountGovernance({ businessAccountId });

await setBusinessAccountGovernance({
  businessAccountId,
  governance: {
    ...current,
    addMember: [
      {
        id: 'cfo-signoff',
        schemaVersion: 1,
        requiredApprovals: 1,
        eligibleApproverRoles: ['cfo'],
      },
    ],
  },
});

The custom role must already exist when the requirement is set, and a role cannot be deleted while a requirement still names it. See Governance for the full requirement fields and Approvals for the model and how a signed change becomes a proposal.

Learn

Cookbooks

Implement

Define a role

List roles

Assign a role

Read a member’s custom role

Delete a role

Governance

Next steps

Members & roles

Governance

​Define a role

​List roles

​Assign a role

​Read a member’s custom role

​Delete a role

​Governance

​Next steps

Members & roles

Governance

Define a role

List roles

Assign a role

Read a member’s custom role

Delete a role

Governance

Next steps