Skip to main content
Business Accounts are in early access. Contact your Dynamic account team to enable them for your environment.
The Business Accounts REST API lets an authenticated end user manage team-owned embedded wallets, members, roles, signers, and account policy rules. You can call non-ceremony operations directly over HTTP.

​
Before you start

You need:
  • Your Dynamic environment ID.
  • A valid user JWT issued for that environment.
  • The API base URL, https://app.dynamic.xyz/api/v0.
  • An elevated access token for sensitive operations when step-up authentication is enforced.
Do not use a Dashboard API token that starts with dyn_ for these /sdk/... routes. Business Accounts endpoints act as the authenticated end user and require that user’s JWT.
Send the JWT as a bearer token:
​
string
required
The environment that contains the user and Business Account.
​
string
The Business Account to manage. Operations that create or list accounts do not use this parameter.

​
Understand the access model

A Business Account owns one or more embedded wallets. Members administer the account. Signers can sign with a specific wallet. Membership does not grant signing access, and signing access does not grant administrative permissions. Member roles are:
  • owner: Has full administrative access and can transfer ownership. Each Business Account has exactly one owner.
  • admin: Can update the account, add members, and manage wallets and signers.
  • viewer: Has read-only access.
Signer types are:
  • endUser: A Dynamic user who holds a client key share for the wallet.
  • server: A server-controlled signer.

​
Account operations

These operations can be called directly over HTTP: The account detail response includes the account’s members, wallets, and signers. A request from a user who is not a member returns 404 instead of revealing that the Business Account exists. See the generated Business Accounts endpoint pages in the API Reference for request and response schemas.

​
Member operations

Adding or changing a member updates the permissions represented in that user’s JWT. You can add members as admin or viewer. Use the ownership transfer operation to assign the owner role. The target of an ownership transfer must already be a member. Removing a member also removes that user’s signer access across the Business Account. The request returns 409 if the removal would leave a wallet without an active signer.

​
Wallet and signer operations

You can link an existing user wallet without starting a new MPC ceremony. The link operation transfers the wallet to the Business Account and registers the caller as an endUser signer using the wallet’s existing key share. Removing a wallet also removes its signer and key-share records. Removing a signer does not start a reshare ceremony and does not affect the remaining signers. A signer removal returns 409 if it would leave the wallet without an active signer.
Use the Business Accounts helpers in the JavaScript SDK to create a new Business Account wallet or add a signer. These operations run client-side MPC ceremonies and persist client key shares. Calling the low-level endpoint alone does not complete the flow.

​
Send elevated access tokens

When step-up authentication is enforced for your environment, the sensitive operations in the tables above require an elevated access token with the exact scope shown. Obtain the token by re-verifying the user through a supported step-up method. Then send both tokens:
The API returns 403 if the elevated token is missing, expired, belongs to a different user, or does not contain the required scope. The business_account:transfer_ownership scope is single-use. Do not reuse that token for another ownership transfer.

​
Refresh stale permissions

Business Account permissions are included in the user JWT. A membership, role, wallet, or signer change can make an existing JWT stale. Most Business Accounts management routes check this freshness. A stale request returns:
Handle this response as follows:
1

Refresh the user JWT

Call POST /sdk/{environmentId}/refresh with the current user JWT and the registered device’s x-dynamic-device-nonce, x-dynamic-device-publickey, and x-dynamic-device-signed-nonce headers. Cookie-enabled sessions do not send these headers. The response contains a new JWT with current permissions. The generated “Refresh the JWT auth token” endpoint page documents the response schema. If refresh fails, authenticate the user again and do not retry the original request.
2

Replace the bearer token

Use the new JWT for later requests. Do not continue using the stale JWT.
3

Reauthorize sensitive operations

Attach a valid elevated access token again if the original request required one. If the operation consumed a single-use elevated or MFA proof, repeat the step-up flow instead of replaying the previous proof.
4

Retry once

Retry only a non-ceremony operation, and retry it at most once. Return the error to the application if the retry also returns rbac_stale.
The JavaScript SDK version 1.30.3 and later detects this response, refreshes the JWT, and retries safe requests once. If a wallet operation has already consumed a one-time authorization, the SDK requires the user to reauthorize before the application retries.
Ownership transfer is different. Dynamic revokes the former owner’s session after a successful transfer. The former owner must sign in again instead of refreshing the previous session.

​
Handle common errors

Last modified on October 26, 2026