Step-Up Authentication

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

Most business account modifications require an elevated access token: a short-lived JWT bound to a specific action. The regular session token proves who the user is, but not that they just re-verified their identity, so a call made without the elevated token is rejected with a 403. This page covers how step-up applies to business accounts. For the general model, including verification methods, token lifetimes, and single-use scopes, see Step-Up Authentication.

Which operations require step-up

Operation	Required scope	JavaScript SDK method
Add a signer	`business_account:signer:add`	`addBusinessAccountSigner`
Remove a signer	`business_account:signer:remove`	`removeBusinessAccountSigner`
Add a member	`business_account:member:add`	`addBusinessAccountMember`
Remove a member	`business_account:member:remove`	`removeBusinessAccountMember`
Update a member’s role	`business_account:member:role:update`	`updateBusinessAccountMemberRole`
Transfer ownership	`business_account:transfer_ownership`	`transferBusinessAccountOwnership`
Link a wallet	`business_account:link_wallet`	`addWalletToBusinessAccount`
Remove a wallet	`business_account:wallet:remove`	`removeBusinessAccountWallet`
Add or remove a policy rule	`waas:policy:update`	`upsertAccountPolicyRule`, `removeAccountPolicyRule` and the wallet and signer equivalents

This table covers the most common operations. Other governed operations also require step-up: defining or deleting custom roles, updating governance, and approving or vetoing proposals. addWalletToBusinessAccount attaches an existing wallet to a business account. Adding a signer to a wallet that is not yet in an account first links the wallet, so it also needs business_account:link_wallet. Reads and account or wallet creation do not require step-up: createBusinessAccount, getBusinessAccount, listBusinessAccounts, and createWalletForBusinessAccount all work with the regular session token. createWalletForBusinessAccount creates the wallet inside the account, so no link step is needed. Step-up is independent of approvals. Approval requirements decide whether a change needs approvals from other members before it applies. Step-up decides whether the person initiating the change has recently re-verified their own identity. An operation can require either, both, or neither.

How a user obtains an elevated token

A member obtains an elevated token by re-verifying their identity. There are three paths, and which one applies depends on how the member authenticates. Verify with requested scopes. The member verifies with a passkey, TOTP, email or SMS OTP, social OAuth, or an external wallet signature. The verify call names the scope the operation needs in a requestedScopes array, for example, with a passkey, authenticatePasskeyMFA({ requestedScopes: [TokenScope.BusinessAccountsigneradd] }). See the step-up reference for the other methods. Import TokenScope and authenticatePasskeyMFA from @dynamic-labs-sdk/client. The response carries an elevated token bound to that scope, and the SDK stores it and attaches it to the next call automatically. When the member has MFA methods registered, the SDK sends an MFA token in the x-mfa-auth-token header instead of an elevated token. External auth assertion. If your backend issues its own JWTs, registered through the environment’s JWKS URL, it can mint a short-lived JWT and pass it to requestExternalAuthElevatedToken({ externalJwt }), which returns an elevated token that the SDK stores. The scope claim is a space-delimited list of scopes. The external auth guide lists all required claims. No user interaction is needed, which suits server-driven flows. Challenge flow. Before a governed call, checkStepUpAuth({ scope }) reports whether step-up is required and which credentials the member can verify with. An app can use that response to drive its own verification UI, then complete verification with the requested scope. An elevated token is short-lived and scoped to the action it was issued for. A token minted to add a signer does not authorize removing a member, and an expired token fails with the same 403 as a missing one, so the member verifies again. The 403 response is JSON with an error string. A missing token returns Elevated authentication required. Please reauthenticate with a registered credential. An invalid or expired token returns Invalid or expired elevated access token. These messages can change, so branch on the status code, not the text. In the JavaScript SDK, catch an APIError whose status is 403, as shown in the step-up reference.

Next steps

Step-up auth

Check for a required step-up and obtain an elevated token with the JavaScript SDK.