Business Account Invitations

Business Accounts are in early access. See Invitations for the lifecycle and security model.

When invitations are enabled for an environment, adding a member or end-user signer creates pending access. The invited user must sign in and accept before becoming an active member or signer.

Create a member invitation

addBusinessAccountMember can return one of three outcomes:

BusinessAccountActionRequired when the addition still needs approvals
BusinessAccountMemberInvite when the invited user must accept
BusinessAccountMember when the user is already active or invitations are not enabled

Narrow the result before using it. An invitation receipt contains the supplied identifier and invitation ID, but omits the resolved user ID.

import {
  addBusinessAccountMember,
  isBusinessAccountActionRequired,
  isBusinessAccountMemberInvite,
} from '@dynamic-labs-sdk/client/waas';

const result = await addBusinessAccountMember({
  businessAccountId,
  targetIdentity: {
    identifier: 'teammate@acme.com',
    identifierType: 'email',
  },
  role: 'admin',
});

if (isBusinessAccountActionRequired(result)) {
  console.log('Approval required', result.proposalId);
} else if (isBusinessAccountMemberInvite(result)) {
  console.log('Invitation created', result.id, result.identifierValue);
} else {
  console.log('Member is already active', result.userId);
}

Adding a member requires step-up authentication with business_account:member:add. If the account governs addMember, complete its proposal flow before an invitation is sent. See Step-up authentication and Governance.

Show invitations to the recipient

Call getBusinessAccountInvites after the user signs in. The request does not accept an email or user ID. The backend derives the recipient from the authenticated session.

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

const { invites } = await getBusinessAccountInvites();

for (const invite of invites) {
  console.log(invite.id, invite.businessAccountName, invite.kind);
}

The response includes unexpired invitations that are ready for the signed-in user to accept. A member invitation activates membership. A signer invitation activates membership and the staged signer share set for walletId.

Accept an invitation

Pass the invitation ID to acceptBusinessAccountInvite. The SDK refreshes authentication after acceptance so the new role and business account are available to subsequent SDK calls.

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

const { invite, member } = await acceptBusinessAccountInvite({
  inviteId: invites[0].id,
});

console.log(invite.status, member.businessAccountId, member.role);

Acceptance is idempotent. Repeating a successful acceptance returns the accepted invitation and active member.

React acceptance prompt

Use useGetBusinessAccountInvites to show a prompt after sign-in and useAcceptBusinessAccountInvite to accept. The mutation refreshes the invitation and business account queries. Redirect from onSuccess if your application has a business account route.

import {
  useAcceptBusinessAccountInvite,
  useGetBusinessAccountInvites,
} from '@dynamic-labs-sdk/react-hooks';

const BusinessAccountInvitation = () => {
  const { data } = useGetBusinessAccountInvites();
  const invite = data?.invites[0];
  const { mutate: accept, isPending } = useAcceptBusinessAccountInvite({
    mutateParams: {
      onSuccess: ({ invite: accepted }) => {
        window.location.assign(
          `/business-accounts/${accepted.businessAccountId}`,
        );
      },
    },
  });

  if (!invite) return null;

  return (
    <div role="dialog" aria-labelledby="business-account-invitation-title">
      <h2 id="business-account-invitation-title">Business account invitation</h2>
      <p>{invite.businessAccountName} has added you to a business account.</p>
      <button
        type="button"
        disabled={isPending}
        onClick={() => accept({ inviteId: invite.id })}
      >
        Accept
      </button>
    </div>
  );
};

List invitations as an administrator

Use listBusinessAccountMemberInvites to render pending invitations for a business account. These inviter-facing receipts contain the identifier and invitation ID needed for cancellation, without exposing the resolved user ID.

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

const { invites } = await listBusinessAccountMemberInvites({
  businessAccountId,
});

for (const invite of invites) {
  console.log(invite.id, invite.identifierValue, invite.status, invite.kind);
}

The matching React query is useListBusinessAccountMemberInvites({ businessAccountId }).

Cancel an invitation

Cancel with the invitation ID returned by addBusinessAccountMember or listBusinessAccountMemberInvites. Cancellation uses the business_account:member:remove step-up scope and can require the account’s member-removal approvals.

import {
  cancelBusinessAccountMemberInvite,
  isBusinessAccountActionRequired,
} from '@dynamic-labs-sdk/client/waas';

const result = await cancelBusinessAccountMemberInvite({
  businessAccountId,
  inviteId,
});

if (isBusinessAccountActionRequired(result)) {
  console.log('Approval required', result.proposalId);
} else {
  console.log('Invitation canceled', result.id, result.status);
}

The matching React mutation is useCancelBusinessAccountMemberInvite. It refreshes useListBusinessAccountMemberInvites after a successful cancellation. Canceling a signer invitation also revokes its staged signer and key-share resources. The recipient can no longer accept it.

Signer invitations

addBusinessAccountSigner still performs the reshare ceremony and returns a shareSetId after the ceremony succeeds. When invitations are enabled, that share set remains pending and cannot sign until the recipient accepts the resulting kind: 'signer' invitation. Do not interpret { shareSetId } as active signing access. Show the outstanding invitation by calling listBusinessAccountMemberInvites, and show the recipient’s acceptance prompt with getBusinessAccountInvites or useGetBusinessAccountInvites.

Learn

Cookbooks

Implement

Business Account Invitations

Create a member invitation

Show invitations to the recipient

Accept an invitation

React acceptance prompt

List invitations as an administrator

Cancel an invitation

Signer invitations

Next steps

Members and roles

Manage signers

​Create a member invitation

​Show invitations to the recipient

​Accept an invitation

​React acceptance prompt

​List invitations as an administrator

​Cancel an invitation

​Signer invitations

​Next steps

Members and roles

Manage signers

Create a member invitation

Show invitations to the recipient

Accept an invitation

React acceptance prompt

List invitations as an administrator

Cancel an invitation

Signer invitations

Next steps