> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Step-Up Authentication

> Why sensitive business account operations require an elevated access token, and the ways a user can obtain one.

> [!NOTE]
>
> Business Accounts are in **early access**. See [Business Accounts](https://docs.dynamic.xyz/docs/business-accounts/accounts.md) 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](https://docs.dynamic.xyz/docs/auth/step-up-auth.md).

## 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](https://docs.dynamic.xyz/docs/javascript/reference/business-accounts/custom-roles.md), updating [governance](https://docs.dynamic.xyz/docs/javascript/reference/business-accounts/governance.md), and approving or vetoing [proposals](https://docs.dynamic.xyz/docs/business-accounts/approvals.md).

`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](https://docs.dynamic.xyz/docs/business-accounts/approvals.md). 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](https://docs.dynamic.xyz/docs/javascript/reference/business-accounts/step-up-auth.md) 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](https://docs.dynamic.xyz/docs/javascript/authentication-methods/step-up-auth/external-auth.md) 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](https://docs.dynamic.xyz/docs/javascript/reference/business-accounts/step-up-auth.md).

## Next steps

> [card] [Step-up auth](https://docs.dynamic.xyz/docs/javascript/reference/business-accounts/step-up-auth.md)
>
> Check for a required step-up and obtain an elevated token with the JavaScript SDK.

> [card] [Step-Up Authentication](https://docs.dynamic.xyz/docs/auth/step-up-auth.md)
>
> The general step-up model: verification methods, scopes, and token lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.