Check User Scopes

checkUserScopes

Checks whether a user has all the specified scopes.

Dynamic assigns scopes to users as they satisfy requirements — for example, user:basic is granted once a user completes MFA, device registration, and required fields. checkUserScopes lets you verify that a user holds any set of scopes you need.

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

const user = dynamicClient.user;

const hasBasicScope = checkUserScopes({ user, scopes: ['user:basic'] });

Parameters

Parameter	Type	Description
user	User	The authenticated user object from dynamicClient.user.
scopes	string[]	Scope strings the user must have.

Returns

boolean — true if the user has every scope in scopes, false otherwise.

What is user:basic?

user:basic is the scope Dynamic grants once a user has satisfied all Dynamic-controlled requirements:

• Required fields (KYC) filled
• MFA authentication completed (if configured)
• Recovery codes acknowledged (if MFA is enabled)
• Device registered (if required)

This is the scope that gates embedded wallet creation and other privileged operations on the backend.

Composing your own readiness check

“Is the user ready?” is your app’s business logic — not ours. Dynamic only controls the user:basic gate. Everything else — wallets connected, NFTs held, plans activated, terms accepted — is yours to compose.

Use checkUserScopes as a building block alongside your own conditions:

import { checkUserScopes, isAnyWalletAccountConnected } from '@dynamic-labs-sdk/client';

const isUserReady = () => {
  const user = dynamicClient.user;
  if (!user) return false;

  // Dynamic's requirements satisfied
  const passedDynamicGates = checkUserScopes({ user, scopes: ['user:basic'] });

  // Your app-specific logic
  const hasWallet = isAnyWalletAccountConnected();
  const acceptedTerms = myApp.hasAcceptedTerms(user.id);

  return passedDynamicGates && hasWallet && acceptedTerms;
};

Deprecation of isUserOnboardingComplete

isUserOnboardingComplete is deprecated. Use checkUserScopes({ user, scopes: ['user:basic'] }) instead.

isUserOnboardingComplete checked the same Dynamic-controlled requirements that user:basic represents, but its name implied it could tell you whether a user had “completed onboarding”, which is inherently app-specific. The replacement makes the contract explicit: you check scopes, and you decide what “ready” means for your app.

Migration:

Before:

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

const ready = isUserOnboardingComplete();

After:

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

const user = dynamicClient.user;
const ready = checkUserScopes({ user, scopes: ['user:basic'] });

Checking individual requirements

If you need finer-grained checks (for example, to show specific UI for each pending step), you can still use the individual helpers:

import {
  isUserMissingMfaAuth,
  isPendingRecoveryCodesAcknowledgment,
  isDeviceRegistrationRequired,
} from '@dynamic-labs-sdk/client';

const user = dynamicClient.user;

const hasMissingFields = Boolean(user.missingFields?.length);
const needsMfa = isUserMissingMfaAuth();
const needsRecoveryCodes = isPendingRecoveryCodesAcknowledgment();
const needsDeviceRegistration = isDeviceRegistrationRequired(user);

Related

• isUserMissingMfaAuth — Check if user needs MFA authentication
• isPendingRecoveryCodesAcknowledgment — Check if recovery codes need acknowledgment
• Device Registration — Device registration flow
• User and Session Management — Managing user sessions