SignUp
The SignUp object holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. Once a sign-up is complete, a new user is created.
The following steps outline the sign-up process:
- Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the create() method.
 - Prepare the verification.
 - Attempt to complete the verification.
 - If the verification is successful, set the newly created session as the active session by passing the 
SignIn.createdSessionIdto the setActive() method on theClerkobject. 
Properties
- Name
 id- Type
 string | undefined- Description
 The unique identifier of the current sign-up.
- Name
 status- Type
 'missing_requirements' | 'complete' | 'abandoned' | null- Description
 The status of the current sign-up. The following values are supported:
complete:The user has been created and the custom flow can proceed tosetActive()to create session.missing_requirements:A requirement is unverified or missing from the Email, Phone, Username settings. For example, in the Clerk Dashboard, the Password setting is required but a password wasn't provided in the custom flow.abandoned:The sign-up has been inactive for over 24 hours.
- Name
 requiredFields- Type
 string[]- Description
 An array of all the required fields that need to be supplied and verified in order for this sign-up to be marked as complete and converted into a user.
- Name
 optionalFields- Type
 string[]- Description
 An array of all the fields that can be supplied to the sign-up, but their absence does not prevent the sign-up from being marked as complete.
- Name
 missingFields- Type
 string[]- Description
 An array of all the fields whose values are not supplied yet but they are mandatory in order for a sign-up to be marked as complete.
- Name
 unverifiedFields- Type
 string[]- Description
 An array of all the fields whose values have been supplied, but they need additional verification in order for them to be accepted. Examples of such fields are
emailAddressandphoneNumber.
- Name
 verifications- Type
 SignUpVerifications- Description
 An object that contains information about all the verifications that are in-flight.
- Name
 username- Type
 string | null- Description
 The username supplied to the current sign-up. Only supported if username is enabled in the instance settings.
- Name
 emailAddress- Type
 string | null- Description
 The email address supplied to the current sign-up. Only supported if email address is enabled in the instance settings.
- Name
 phoneNumber- Type
 string | null- Description
 The user's phone number in E.164 format. Only supported if phone number is enabled in the instance settings.
- Name
 web3Wallet- Type
 string | null- Description
 The Web3 wallet address, made up of 0x + 40 hexadecimal characters. Only supported if Web3 authentication is enabled in the instance settings.
- Name
 hasPassword- Type
 boolean- Description
 The value of this attribute is true if a password was supplied to the current sign-up. Only supported if Password is enabled in the instance settings.
- Name
 firstName- Type
 string | null- Description
 The first name supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.
- Name
 lastName- Type
 string | null- Description
 The last name supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.
- Name
 unsafeMetadata- Type
 - SignUpUnsafeMetadata
 - Description
 Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
- Name
 createdSessionId- Type
 string | null- Description
 The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.
- Name
 createdUserId- Type
 string | null- Description
 The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.
- Name
 abandonAt- Type
 number | null- Description
 The epoch numerical time when the sign-up was abandoned by the user.
Methods
attemptEmailAddressVerification()
Attempts to verify an email address by validating the one-time verification code provided by the user against the code sent during the prepare verification step. This is a convenience method that wraps SignUp.attemptVerification() with the 'email_code' strategy.
By default, this method is equivalent to calling SignUp.attemptVerification({ strategy: 'email_code', code }). The verification attempt will fail if the code is invalid or has expired.
function attemptEmailAddressVerification(
  params: AttemptEmailAddressVerificationParams,
): Promise<SignUpResource>- Name
 code- Type
 string- Description
 The code that was sent to the user via email.
attemptPhoneNumberVerification()
Attempts to verify a phone number by validating the one-time verification code provided by the user against the code sent during the prepare verification step. This is a convenience method that wraps SignUp.attemptVerification() with the 'phone_code' strategy.
By default, this method is equivalent to calling SignUp.attemptVerification({ strategy: 'phone_code', code }). The verification attempt will fail if the code is invalid or has expired.
function attemptPhoneNumberVerification(
  params: AttemptPhoneNumberVerificationParams,
): Promise<SignUpResource>- Name
 code- Type
 string- Description
 The code that was sent to the user via SMS.
attemptVerification()
Attempts to complete a pending verification process for the specified verification strategy. This method must be called after initiating verification via SignUp.prepareVerification(). The verification attempt will validate the provided verification parameters (code, signature, etc.) against the pending verification request.
Depending on the strategy, the method parameters could differ.
function attemptVerification(params: AttemptVerificationParams): Promise<SignUp>- Name
 strategy- Type
 'phone_code' | 'email_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'- Description
 The verification strategy to complete the user's sign-up request against. The following strategies are supported:
'phone_code': Validates an SMS with a unique token to input.'email_code': Validates an email with a unique token to input.'web3_metamask_signature': The verification will attempt to be completed using the user's Web3 wallet address via Metamask. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.'web3_coinbase_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via Coinbase Wallet. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.'web3_okx_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via OKX Wallet. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.
- Name
 code- Type
 string- Description
 Required if
strategyis set to'phone_code'or'email_code'. The code that was sent to the user.
- Name
 signature- Type
 string- Description
 Required if
strategyis set to'web3_metamask_signature','web3_coinbase_wallet_signature', or'web3_okx_wallet_signature'. The signature that was sent to the user via the Web3 verification strategy.
attemptWeb3WalletVerification()
Attempts to verify a Web3 wallet address by validating the cryptographic signature generated by the wallet against the nonce provided during the prepare verification step. This is a convenience method that wraps SignUp.attemptVerification() with Web3 wallet strategies.
By default, this method is equivalent to calling SignUp.attemptVerification({ strategy: 'web3_metamask_signature', signature }). The verification attempt will fail if the signature is invalid or the nonce has expired.
function attemptWeb3WalletVerification(params: AttemptWeb3WalletVerificationParams): Promise<SignUp>- Name
 signature- Type
 string- Description
 The signature that was generated after prepareVerification was called.
authenticateWithCoinbaseWallet()
Initiates an authentication flow using the Coinbase Wallet browser extension, allowing users to authenticate via their Web3 wallet address. This method prompts the user to connect their Coinbase Wallet and sign a message to verify ownership of the wallet address.
function authenticateWithCoinbaseWallet(
  params?: SignUpAuthenticateWithWeb3Params,
): Promise<SignUpResource>const signUp = await clerk.signUp.authenticateWithCoinbaseWallet()authenticateWithMetamask()
Initiates an authentication flow using the MetaMask browser extension, allowing users to authenticate via their Ethereum wallet address. This method prompts the user to connect their MetaMask wallet and sign a message to verify ownership of the wallet address.
function authenticateWithMetamask(
  params?: SignUpAuthenticateWithWeb3Params,
): Promise<SignUpResource>const signUp = await clerk.signUp.authenticateWithMetamask()authenticateWithOKXWallet()
Initiates an authentication flow using the OKX Wallet browser extension, allowing users to authenticate via their Web3 wallet address. This method prompts the user to connect their OKX Wallet and sign a message to verify ownership of the wallet address.
function authenticateWithOKXWallet(
  params?: SignUpAuthenticateWithWeb3Params,
): Promise<SignUpResource>- Name
 unsafeMetadata- Type
 - SignUpUnsafeMetadata
 - Description
 Metadata that can be read and set from the frontend and the backend. Once the sign-up is complete, the value of this field will be automatically copied to the created user's unsafe metadata (
User.unsafeMetadata). One common use case is to collect custom information about the user during the sign-up process and store it in this property. Read more about unsafe metadata.
const signUp = await clerk.signUp.authenticateWithOKXWallet()authenticateWithRedirect()
Signs up a user via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.
function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promise<void>- Name
 redirectUrl- Type
 string- Description
 The full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple
/sso-callbackroute that either calls Clerk.handleRedirectCallback or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.
- Name
 redirectUrlComplete- Type
 string- Description
 The full URL or path to navigate to after the OAuth or SAML flow completes.
- Name
 continueSignUp- Type
 boolean | undefined- Description
 Whether to continue (i.e. PATCH) an existing
SignUp(if present) or create a newSignUp.
- Name
 strategy- Type
 'oauth_<provider>' | 'saml' | 'enterprise_sso'- Description
 The strategy to use for authentication. The following strategies are supported:
'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for<provider>.'saml'(deprecated): Deprecated in favor of'enterprise_sso'. The user will be authenticated with their SAML account.'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.
- Name
 identifier- Type
 string | undefined- Description
 Identifier to use for targeting an enterprise connection at sign-up.
- Name
 emailAddress- Type
 string | undefined- Description
 Email address to use for targeting an enterprise connection at sign-up.
- Name
 legalAccepted?- Type
 boolean- Description
 A boolean indicating whether the user has agreed to the legal compliance documents.
Example
For OAuth connections, see the custom flow for OAuth connections. For enterprise connections, see the custom flow for enterprise connections.
authenticateWithPopup()
Opens a popup window to allow a user to sign up via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.
function authenticateWithPopup(params: AuthenticateWithPopupParams): Promise<void>- Name
 redirectUrl- Type
 string- Description
 The full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple
/sso-callbackroute that either calls Clerk.handleRedirectCallback or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.
- Name
 redirectUrlComplete- Type
 string- Description
 The full URL or path to navigate to after the OAuth or SAML flow completes.
- Name
 strategy- Type
 'oauth_<provider>' | 'saml' | 'enterprise_sso'- Description
 The strategy to use for authentication. The following strategies are supported:
'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for<provider>.'saml'(deprecated): Deprecated in favor of'enterprise_sso'. The user will be authenticated with their SAML account.'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.
- Name
 continueSignUp?- Type
 boolean | undefined- Description
 Whether to continue (i.e. PATCH) an existing
SignUp(if present) or create a newSignUp.
- Name
 emailAddress?- Type
 string | undefined- Description
 Email address to use for targeting an enterprise connection at sign-up.
- Name
 identifier?- Type
 string | undefined- Description
 Identifier to use for targeting an enterprise connection at sign-up.
- Name
 legalAccepted?- Type
 boolean- Description
 A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
 popup?- Type
 Window- Description
 A reference to a popup window opened via
window.open().
Example
For OAuth connections, see the custom flow for OAuth connections. For enterprise connections, see the custom flow for enterprise connections.
authenticateWithWeb3()
Initiates a Web3 authentication flow by verifying the user's ownership of a blockchain wallet address through cryptographic signature verification. This method enables decentralized authentication without requiring traditional credentials.
function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise<SignUpResource>- Name
 identifier- Type
 string- Description
 The user's Web3 ID
- Name
 generateSignature- Type
 (opts: GenerateSignatureParams) => Promise<string>- Description
 The method of how to generate the signature for the Web3 sign-in. See GenerateSignatureParams for more information.
- Name
 strategy?- Type
 Web3Strategy- Description
 The Web3 verification strategy.
- Name
 legalAccepted?- Type
 boolean- Description
 A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
 identifier- Type
 string- Description
 The user's Web3 wallet address.
- Name
 nonce- Type
 string- Description
 The cryptographic nonce used in the sign-in.
- Name
 provider?- Type
 Web3Provider- Description
 The Web3 provider to generate the signature with.
- Name
 legalAccepted?- Type
 boolean- Description
 A boolean indicating whether the user has agreed to the legal compliance documents.
const signUp = await clerk.signUp.authenticateWithWeb3({
  identifier: '0x1234567890123456789012345678901234567890',
})create()
Returns a new SignUp object based on the params you pass to it, stores the sign-up lifecycle state in the status property, and deactivates any existing sign-up process the client may already have in progress. Use this method to initiate a new sign-up process.
What you must pass to params depends on which sign-up options you have enabled in your Clerk application instance.
Optionally, you can complete the sign-up process in one step if you supply the required fields to create(). Otherwise, Clerk's sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.
function create(params: SignUpCreateParams): Promise<SignUpResource>- Name
 strategy- Type
 'oauth_<provider>' | 'saml' | 'enterprise_sso' | 'ticket' | 'google_one_tap'- Description
 The strategy to use for the sign-up flow. The following strategies are supported:
'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for<provider>.'saml'(deprecated): Deprecated in favor of'enterprise_sso'. The user will be authenticated with their SAML account.'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.'ticket': The user will be authenticated via the ticket or token generated from the Backend API.'google_one_tap': The user will be authenticated with the Google One Tap UI. It's recommended to use authenticateWithGoogleOneTap() instead, as it will also set the user's current session as active for you.
- Name
 firstName- Type
 string | null- Description
 The user's first name. Only supported if First and last name is enabled.
- Name
 lastName- Type
 string | null- Description
 The user's last name. Only supported if First and last name is enabled.
- Name
 password- Type
 string | null- Description
 The user's password. Only supported if Password is enabled.
- Name
 emailAddress- Type
 string | null- Description
 The user's email address. Only supported if Email address is enabled. Keep in mind that the email address requires an extra verification process.
- Name
 phoneNumber- Type
 string | null- Description
 The user's phone number in E.164 format. Only supported if phone number is enabled. Keep in mind that the phone number requires an extra verification process.
- Name
 web3Wallet- Type
 string | null- Description
 Required if Web3 authentication is enabled. The Web3 wallet address, made up of 0x + 40 hexadecimal characters.
- Name
 username- Type
 string | null- Description
 The user's username. Only supported if Username is enabled.
- Name
 unsafeMetadata- Type
 - SignUpUnsafeMetadata
 - Description
 Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created
Userobject.
- Name
 redirectUrl- Type
 string- Description
 If
strategyis set to'oauth_<provider>'or'enterprise_sso', this specifies full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple/sso-callbackroute that either calls Clerk.handleRedirectCallback() or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.If
strategyis set to'email_link', this specifies The full URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.
- Name
 actionCompleteRedirectUrl- Type
 string- Description
 Optional if
strategyis set to'oauth_<provider>'or'enterprise_sso'. The full URL or path that the user will be redirected to after successful authorization from the OAuth provider and Clerk sign-in.
- Name
 ticket- Type
 string- Description
 Required if
strategyis set to'ticket'. The ticket or token generated from the Backend API.
- Name
 transfer- Type
 boolean- Description
 When set to
true, theSignUpwill attempt to retrieve information from the activeSignIninstance and use it to complete the sign-up process. This is useful when you want to seamlessly transition a user from a sign-in attempt to a sign-up attempt.
- Name
 legalAccepted- Type
 boolean- Description
 A boolean indicating whether the user has agreed to the legal compliance documents.
- Name
 oidcPrompt- Type
 string- Description
 Optional if
strategyis set to'oauth_<provider>'or'enterprise_sso'. The value to pass to the OIDCpromptparameter in the generated OAuth redirect URL.
- Name
 oidcLoginHint- Type
 string- Description
 Optional if
strategyis set to'oauth_<provider>'or'enterprise_sso'. The value to pass to the OIDClogin_hintparameter in the generated OAuth redirect URL.
function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUp>
  cancelEmailLinkFlow: () => void
}Sets up a sign-up with email link flow. Calling createEmailLinkFlow() will return two functions.
The first function is async and starts the email link flow, preparing an email link verification. It sends the email link email and starts polling for verification results. The signature is startEmailLinkFlow({ redirectUrl: string }) => Promise<SignUpResource>.
The second function can be used to stop polling at any time, allowing for full control of the flow and cleanup. The signature is cancelEmailLinkFlow() => void.
function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUpResource>
  cancelEmailLinkFlow: () => void
}createEmailLinkFlow() returns
createEmailLinkFlow returns an object with two functions:
- Name
 startEmailLinkFlow- Type
 (params: StartEmailLinkFlowParams) => Promise<SignUp>- Description
 Function to start the email link flow. It prepares an email link verification and polls for the verification result.
- Name
 redirectUrl- Type
 string- Description
 The full URL that the user will be redirected to when they visit the email link.
prepareEmailAddressVerification()
Initiates an email verification process by sending a one-time verification code to the email address associated with the current sign-up attempt. This is a convenience method that wraps SignUp.prepareVerification() with the 'email_code' strategy.
By default, this method is equivalent to calling SignUp.prepareVerification({ strategy: 'email_code' }). It can be customized via the PrepareEmailAddressVerificationParams to use alternative verification strategies like email links.
function prepareEmailAddressVerification(
  params?: PrepareEmailAddressVerificationParams,
): Promise<SignUpResource>- Name
 strategy- Type
 'email_code' | 'email_link'- Description
 The verification strategy to validate the user's sign-up request. The following strategies are supported:
'email_code': Send an email with a unique token to input.'email_link': Send an email with a link which validates sign-up.
- Name
 redirectUrl- Type
 string- Description
 Required if
strategyis set to'email_link'. The full URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.
preparePhoneNumberVerification()
Initiates a phone number verification process by sending a one-time verification code (OTP) via SMS to the phone number associated with the current sign-up attempt. This is a convenience method that wraps SignUp.prepareVerification() with the 'phone_code' strategy.
By default, this method is equivalent to calling SignUp.prepareVerification({ strategy: 'phone_code' }). The verification process will fail if the phone number is invalid, unreachable, or has already been verified. The sent verification code has a limited validity period and can only be used once.
function preparePhoneNumberVerification(
  params?: PreparePhoneNumberVerificationParams,
): Promise<SignUpResource>- Name
 strategy- Type
 'phone_code'- Description
 The verification strategy to validate the user's sign-up request. The following strategies are supported:
'phone_code': Send an SMS with a unique token to input.
prepareVerification()
Initiates the verification process for a field that requires validation during sign-up. This method prepares the necessary verification flow based on the specified strategy, such as sending verification codes, generating OAuth URLs, or preparing Web3 wallet signatures.
function prepareVerification(params: PrepareVerificationParams): Promise<SignUpResource>- Name
 strategy- Type
 'phone_code' | 'email_code' | 'email_link' | 'oauth_<provider>' | 'saml' | 'enterprise_sso' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'- Description
 The verification strategy to validate the user's sign-up request. The following strategies are supported:
'phone_code': User will receive a one-time authentication code via SMS.'email_code': Send an email with a unique token to input.'email_link': Send an email with a link which validates sign-up.'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for<provider>.'saml'(deprecated): Deprecated in favor of'enterprise_sso'. The user will be authenticated with their SAML account.'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.'web3_metamask_signature': The verification will attempt to be completed using the user's Web3 wallet address via Metamask. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.'web3_coinbase_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via Coinbase Wallet. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.'web3_okx_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via OKX Wallet. Theweb3_wallet_idparameter can also be specified to select which of the user's known Web3 wallets will be used.
- Name
 redirectUrl- Type
 string- Description
 If
strategyis set to'oauth_<provider>'or'enterprise_sso', this specifies the full URL or path that the OAuth provider should redirect to after successful authorization. Typically, this will be a simple/sso-callbackroute that either calls Clerk.handleRedirectCallback() or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.If
strategyis set to'email_link', this specifies The full URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.
- Name
 actionCompleteRedirectUrl?- Type
 string- Description
 The full URL or path that the user will be redirected to after successful authorization from the OAuth provider and Clerk sign-in.
- Name
 oidcPrompt?- Type
 string- Description
 Optional if
strategyis set to'oauth_<provider>'or'enterprise_sso'. The value to pass to the OIDCpromptparameter in the generated OAuth redirect URL.
- Name
 oidcLoginHint?- Type
 string- Description
 Optional if
strategyis set to'oauth_<provider>'or'enterprise_sso'. The value to pass to the OIDClogin_hintparameter in the generated OAuth redirect URL.
prepareWeb3WalletVerification()
Initiates a verification process for a Web3 wallet by sending the wallet address to the server and retrieving a nonce that must be cryptographically signed by the wallet. This is a convenience method that wraps SignUp.prepareVerification() with Web3 wallet strategies.
By default, this method is equivalent to calling SignUp.prepareVerification({ strategy: 'web3_metamask_signature' }). The verification process will fail if the wallet address is invalid or has already been verified. The returned nonce has a limited validity period and can only be used once.
function prepareWeb3WalletVerification(
  params?: PrepareWeb3WalletVerificationParams,
): Promise<SignUpResource>- Name
 strategy- Type
 'web3_metamask_signature'|'web3_coinbase_wallet_signature'|'web3_okx_wallet_signature'- Description
 The verification strategy to validate the user's sign-up request. The following strategies are supported:
'web3_metamask_signature': User will need to sign a message and generate a signature using MetaMask browser extension.'web3_coinbase_wallet_signature': User will need to sign a message and generate a signature using Coinbase Wallet.'web3_okx_wallet_signature': User will need to sign a message and generate a signature using OKX Wallet.
update()
Updates the current SignUp.
function update(params: SignUpUpdateParams): Promise<SignUpResource>SignUpUpdateParams
SignUpUpdateParams is a mirror of SignUpCreateParams with the same fields and types, depending on the configuration of the instance.
Feedback
Last updated on