useCapxulOrgRoles

Query hook for the roles defined on an organization — labels, role keys, and spend caps, scoped by org id.

Reads the roles defined on an organization — each a label with a definition: spend caps, sub-account scope, and management permissions. This is a read; making the role set enforceable is useCapxulOrgDeployRoles, and granting a role to a member is useCapxulAssignRole.

Import

import { useCapxulOrgRoles } from "@capxul/sdk-react";

Usage

"use client";

import type { OrgId } from "@capxul/sdk";
import { useCapxulOrgRoles } from "@capxul/sdk-react";

function RoleList({ orgId }: { orgId: OrgId }) {
  const roles = useCapxulOrgRoles(orgId);

  if (roles.isLoading) return <p>Loading roles…</p>;
  if (roles.error) return <p>{roles.error.message}</p>;

  return (
    <ul>
      {roles.data.map((role) => {
        const perTx = role.definition.spend?.perTx;
        return (
          <li key={role.roleKey}>
            {role.label}
            {perTx
              ? ` — up to ${perTx.value} ${perTx.currency} per transaction`
              : " — no per-transaction cap"}
          </li>
        );
      })}
    </ul>
  );
}

Parameters

orgId

OrgId | undefined

The organization whose roles to read. The query stays disabled while orgId is undefined, so you can pass the result of another query directly — no manual gating needed.

options

UseCapxulOrgRolesOptions | undefined

Prop

Type

Return type

import { type UseCapxulOrgRolesReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly RoleView[], CapxulError>

data is a list of RoleView records:

Field	Type	Description
`orgId`	`OrgId`	The org the role is defined on.
`label`	`string`	The role's display label (for example `"Owner"`).
`roleKey`	`RoleKey`	The enforced key, derived deterministically from the label.
`definition`	`RoleDefinition`	The full role definition (below).

A RoleDefinition carries:

Field	Type	Description
`label`	`string`	The role's label.
`spend`	`RoleSpendCap \| undefined`	Platform-enforced spend caps: `perTx` and `perDay` (both `Money`) plus `toRecipients` (`"anyone"` or an allowed recipient list). An omitted axis is unbounded — the Owner role omits all of them.
`subAccounts`	`{ scope: "all" \| readonly SubAccountId[] } \| undefined`	Which sub-accounts the role can draw from.
`canManageMembers`	`boolean \| undefined`	Whether the role can invite and remove members.
`canManageRoles`	`boolean \| undefined`	Whether the role can manage the role set itself.

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "org", orgId, "roles"] — org-scoped. Invalidated on success by useCapxulOrgDeployRoles for the same org.

Client method

This hook wraps client.org(orgId).roles() — the entity-scoped org bundle on the core SDK.

useCapxulOrgRoles

On this page