Establishing User Identity and Acquiring a Session Token

Behind the scenes, you as a developer will have to go through a few essential steps to set up and initialize a user. In a theoretical sense, we will explore these steps next: creating your first user and initializing their wallets. These steps include creating a user, creating a session token, and initializing the user account, where you will also create a wallet for the user via Circle's APIs. At the end of these steps, you can then prompt your end-user to complete the account setup in your sample app.

Once you've absorbed the theory behind these steps, you'll find a Try It Out component at the end. This tool handles all of these steps for you, making your experience with the QuickStart guide smoother and more user-friendly.

Let's delve into the process!

  • 1

    Create a new user

    To begin the end-to-end process, you must create and initialize the users who will ultimately be using your application. A user, representing the end-user of your app, is identified through a userID. This userID serves as the account identifier encompassing all associated wallets, assets, and transactions for that specific user.
    You can use a UUID format for the userID or any other format. It must be at least five characters long.

    Create User

    At Circle, we leave user management entirely in your hands. This allows you to keep control of your processes and ensures that your user data stays securely in your system. We simply require a UUID to identify each user in our system. This means you, as a developer, maintain full control while working with us using a straightforward yet secure approach.

  • 2

    Acquire a Session Token

    Once you have successfully created a user, you will acquire a session token which authenticates the user's session within your app and has a validity period of 60 minutes.
    Typically, in your app's flow, you would create a session token when the user logs in. Once you have created a session, we will return an encryptionKey and a userToken. The userToken is the session identifier, and the encryptionKey is an encryption and decryption key that is randomly generated to ensure the security of the session.

    Acquire Session Token

  • 3

    Initialize the User Account

    User initialization is a critical step where you create the user account and create a wallet for a specified blockchain at the time of account creation.

    Two fundamental concepts to understand in this step are:

    Idempotent Requests

    When making an initialization request, it is required that you use an idempotency key, a unique identifier for the request, to ensure that subsequent requests with the same key do not create duplicate entities. You can learn more about it in our documentation.


    A challenge is initiated when your end-users are prompted to take a specific action, such as initiating a transaction or executing a smart contract. They serve as checkpoints in the user journey, ensuring that sensitive operations can only be carried out with the user's explicit authorization.

    The first challenge that users encounter involves setting their PIN code and creating a recovery method as part of this initial sign up. The PIN is encrypted during input on the user's personal device, ensuring developers or merchants never have access to user PINs. The recovery method allows users to regain access to their assets in case they forget their PIN code. They have the option to choose security questions, a familiar backup mechanism that enhances the user experience while ensuring that users have full control over their assets.

    Benefits of Challenges: Empowering Users and Enhancing Security

    User Sovereignty and Asset Security

    By setting up a PIN code, users have complete sovereignty over their wallets. Only operations that are authorized by entering the PIN code can be initiated, providing users with peace of mind and control over their assets.

    Enhanced User Experience without Seed Phrase

    By utilizing a unique PIN code and Recovery Method, users can conveniently and securely access their wallets without being burdened by complex seed phrases.

    Now that we understand these two important concepts, we are ready to initialise the user account and create a wallet.

    Initialize User

This Try It Out component will aggregate the explained steps above and return a challengeId, the userToken and the encryptionKey. We will use in the next few steps within the sample app to set up the user.

Try it out:Initialize User

You also have the option to initialize a user without immediately creating wallets for them. Proceed with

setting up a challenge

for PIN configuration.

By following these steps, you have now successfully created a user, establishing their unique identity. We have also initiated our very first challenge by initializing their accounts and associated wallets, acquiring a session toke and creating a challenge.
You can now enter these values into your sample app simulator and you will have completed the configuration.
In the next step, we will play the role of your end-user, and complete the end-user account setup by defining a pin and recovery methods.

Complete Account Setup

After we gathered all necessary parameters, we are now able to use our WebSDK to enter this information and start the set up process that the end user would go through.

Try it out:Initialize User

By entering your App ID and initializing the user session with the UserToken, EncryptionKey, and ChallengeID, you have successfully invoked the account setup for the end-user. This step is crucial when the you want your end-user to set up their wallet, such as during the account creation process.

Now, you will assume the role of the end user and complete the wallet setup. Get ready to experience the effortless setup experience.

🎉 Great job on setting up the WebSDK!

After the sucessful confirmation a wallet was created, you may now proceed with the next step and learn how to check the wallet status!

Need help or have questions?

Here are some helpful links:

🎮Join our Discord Community: Engage, learn, and collaborate.
🛎Visit our Help-Desk Page: Dive into curated FAQs and guides.
📧Direct Email: We're always a message away.
📖Read docs: Check out our developer documentation.
© 2023 Circle Technology Services, LLC. All rights reserved.