Docs

Create user metadata

These methods on the User object help you create data for the user, such as createEmailAddress() and createPhoneNumber().

The following examples assume that you have followed the quickstart in order to add Clerk to your JavaScript application.

createEmailAddress()

Adds an email address for the user. A new EmailAddress will be created and associated with the user.

Warning

Email address must be enabled as an identifier in your Clerk settings for this method to work. See the Identifiers section to learn more.

function createEmailAddress: (params: CreateEmailAddressParams) => Promise<EmailAddress>;

CreateEmailAddressParams

  • Name
    email
    Type
    string
    Description

    The value of the email address

createEmailAddress() returns

TypeDescription
Promise<EmailAddress>This method returns a Promise which resolves to the email address created for the user.

createEmailAddress() example

The following example adds test@test.com as an email address for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  const email = "test@test.com";

  clerk.user.createEmailAddress({ email })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}
index.html
  <div id="app"></div>

  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
    src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>

  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();

      if (Clerk.user) {
        const email = "test@test.com";

        Clerk.user.createEmailAddress({ email })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;

        const signInDiv = document.getElementById("sign-in");

        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

createPhoneNumber()

Adds a phone number for the user. A new PhoneNumber will be created and associated with the user.

Warning

Phone number must be enabled as an identifier in your Clerk settings for this method to work. See the Identifiers section to learn more.

function createPhoneNumber: (params: CreatePhoneNumberParams) => Promise<PhoneNumber>;

CreatePhoneNumberParams

  • Name
    phoneNumber
    Type
    string
    Description

    The value of the phone number, in E.164 format.

createPhoneNumber() returns

TypeDescription
Promise<PhoneNumber>This method returns a Promise which resolves to the PhoneNumber created for the user.

createPhoneNumber() example

The following example adds 15551234567 as a phone number for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  const phoneNumber = "15551234567";

  clerk.user.createPhoneNumber({ phoneNumber })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}
index.html
  <div id="app"></div>

  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
    src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>

  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();

      if (Clerk.user) {
        const phoneNumber = "15551234567";

        Clerk.user.createPhoneNumber({ phoneNumber })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;

        const signInDiv = document.getElementById("sign-in");

        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

createWeb3Wallet()

Adds a web3 wallet for the user. A new Web3Wallet< will be created and associated with the user.

Warning

A Web3 provider must be enabled in your Clerk settings for this method to work. See the Web3 authentication section to learn more.

function createWeb3Wallet: (params: CreateWeb3WalletParams) => Promise<Web3Wallet>;

CreateWeb3WalletParams

  • Name
    web3Wallet
    Type
    string
    Description

    In Ethereum, the address is made up of 0x + 40 hexadecimal characters.

createWeb3Wallet() returns

TypeDescription
Promise<Web3Wallet>This method returns a Promise which resolves to the Web3Wallet created for the user.

createWeb3Wallet() example

The following example adds 0x0123456789ABCDEF0123456789ABCDEF01234567 as a web3 wallet for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  const web3Wallet = "0x0123456789ABCDEF0123456789ABCDEF01234567";

  clerk.user.createWeb3Wallet({ web3Wallet })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}
index.html
  <div id="app"></div>

  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
    src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>

  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();

      if (Clerk.user) {
        const web3Wallet = "0x0123456789ABCDEF0123456789ABCDEF01234567";

        Clerk.user.createWeb3Wallet({ web3Wallet })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;

        const signInDiv = document.getElementById("sign-in");

        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

createExternalAccount()

Adds an external account for the user. A new ExternalAccount will be created and associated with the user. This method is useful if you want to allow an already signed-in user to connect their account with an external provider, such as Facebook, GitHub, etc., so that they can sign in with that provider in the future.

Warning

The social provider that you want to connect to must be enabled in your Clerk settings for this method to work. See the Social connections (OAuth) section to learn more.

function createExternalAccount: (params: CreateExternalAccountParams) => Promise<ExternalAccount>;

CreateExternalAccountParams

  • Name
    strategy
    Type
    OAuthStrategy
    Description

    The strategy corresponding to the OAuth provider. For example: oauth_facebook, oauth_github, etc.

  • Name
    redirectUrl?
    Type
    string
    Description

    The URL to redirect back to once the OAuth flow has succeeded or failed.

  • Name
    additionalScopes?
    Type
    string[]
    Description

    Any additional scopes you would like your user to be prompted to approve.

createExternalAccount() returns

TypeDescription
Promise<ExternalAccount>This method returns a Promise which resolves to the ExternalAccount created for the user.

createExternalAccount() example

After calling createExternalAccount, the initial state of the returned ExternalAccount will be unverified. To initiate the connection with the external provider, redirect the user to the externalAccount.verification.externalVerificationRedirectURL contained in the result of createExternalAccount.

Upon return, inspect within the user.externalAccounts the entry that corresponds to the requested strategy:

  • If the connection succeeded, then externalAccount.verification.status will be verified.
  • If the connection failed, then the externalAccount.verification.status will not be verified and the externalAccount.verification.error will contain the error encountered, which you can present to the user. To learn more about the properties available on verification, see the verification reference.

The following example demonstrates how to add a Notion account as an external account for the user. When the user selects the "Add Notion as a social connection" button, the user will be redirected to Notion to connect their account. After connecting their account, they will be redirected to the / route of your application, and the status of the connection will be displayed.

For the following example, your HTML file should look like this:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Clerk + JavaScript App</title>
  </head>
  <body>
    <div id="app"></div>

    <p>
      Notion verification status:
      <span id="notion-status"></span>
    </p>
    <button id="add-notion">Add Notion as a social connection</button>

    <script type="module" src="/main.js"></script>
  </body>
</html>

And your JavaScript file should look like this:

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  // Find the external account for the provider
  const externalAccount = clerk.user.externalAccounts.find(
    (p) => p.provider === "notion"
  );
  // If the external account exists, display its status
  document.getElementById("notion-status").innerHTML =
    externalAccount.verification.status;

  // When the button is clicked, initiate the connection with the provider
  document.getElementById("add-notion").addEventListener("click", async () => {
    clerk.user
      .createExternalAccount({ strategy: "oauth_notion", redirect_url: "/" })
      .then((externalAccount) => {
        window.location.href =
          externalAccount.verification.externalVerificationRedirectURL;
      })
      .catch((error) => {
        console.log("An error occurred:", error.errors);
      });
  });
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}
index.html
  <div id="app"></div>
  <p>
    Notion verification status:
    <span id="notion-status"></span>
  </p>
  <button id="add-notion">Add Notion as a social connection</button>

  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
    src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>

  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();

      if (Clerk.user) {
        // Find the external account for the provider
        const externalAccount = Clerk.user.externalAccounts.find(
          (p) => p.provider === "notion"
        );
        // If the external account exists, display its status
        document.getElementById("notion-status").innerHTML =
          externalAccount.verification.status;

        // When the button is clicked, initiate the connection with the provider
        document.getElementById("add-notion").addEventListener("click", async () => {
          Clerk.user
            .createExternalAccount({ strategy: "oauth_notion", redirect_url: "/" })
            .then((externalAccount) => {
              window.location.href =
                externalAccount.verification.externalVerificationRedirectURL;
            })
            .catch((error) => {
              console.log("An error occurred:", error.errors);
            });
        });
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;

        const signInDiv = document.getElementById("sign-in");

        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

Feedback

What did you think of this content?
Edit this page on GitHub