We refreshed our doc site!
Bookmarked links may have changed
Read release notesCircle provides several authentication methods that allow you to build an onboarding experience for your application that is familiar to your users. Choose between social logins, email, or PIN and security questions to authenticate your users and create user-controlled wallets for them.
The following table describes the onboarding UX, signing UX, and key management for each authentication method.
Authentication Methods | Onboarding UX | Signing UX | Key Management |
---|---|---|---|
Social logins | Redirects users to the social provider’s login page where they can choose the account with which they want to create wallets. | Circle displays predefined confirmation UIs to allow users to preview and confirm transaction or signature details with one click. You can customize these UIs for on-chain actions relevant to your scenarios. You can also disable confirmation UIs if you want to fully customize the signing UX. | Circle implements a series of cryptographic procedures that protects key shares and stores a part of key shares on the user's device (secure enclave). This ensures that the private key is invoked only when the user performs a transaction request, contract execution, or signature signing from their own device. |
Prompts users to sign up with their email address and sends them an email containing an OTP to verify their identity. | Circle displays predefined confirmation UIs to allow users to preview and confirm transaction or signature details with one click. You can customize these UIs for on-chain actions relevant to your scenarios. You can also disable confirmation UIs if you want to fully customize the signing UX. | Circle implements a series of cryptographic procedures that protects key shares and stores a part of key shares on the user's device (secure enclave). This ensures that the private key is invoked only when the user performs a transaction request, contract execution, or signature signing from their own device. | |
PIN | Prompts users to set up a PIN and answers to security questions. | Circle does not provide UIs for transaction details. After previewing a signature or transaction, users confirm authorization by inputting a PIN or through biometrics, if enabled. | Users are required to set up a PIN code to authorize transactions. They have sole access to their private keys, which ensures privacy and prevents unauthorized access or movement of assets |
The social logins authentication method allows your users to log in to your application with their Google, Facebook, or Apple accounts. This eliminates the need for them to memorize seed phrases for private key management. Once you initialize a user, Circle creates a wallet for them using multi-party computation (MPC) technology.
Additional social providers
If you want your application to offer a different social provider, join Circle on Discord to make your request.
Circles handles the logic for social logins and requires you to:
Once the above conditions are met, you can initialize the SDK.
Lost credentials
For security reasons, Circle cannot help if your user loses their credentials or is blocked by the social identity provider. Your user must reach out to the social provider to recover their credentials. Note that it can take a few weeks to recover a banned Facebook account.
One user ID per social account
Only one user ID can be linked to one social account. For example, if a user signs up using their Google account, and then signs up again using their Apple account, two user IDs are created.
To test how to onboard a user and create a wallet with our sample app on web, see Quickstarts for Social Logins or Email Authentication.
The process for onboarding a user with social logins onto your application is as follows:
POST
request to the /users/social/token
endpoint with deviceId
included in the request body.deviceToken
and deviceEncryptionKey
in the response.performLogin
with deviceToken
anddeviceEncryptionKey
provided.userID
, userToken
, encryptionKey
, refreshToken
, and OAuthInfo
.After you've onboarded your user, you can initialize the user and create a wallet. The process is as follows:
POST
request to the/user/initialize
endpoint withuserToken
included in the request body.challengeId
in the response.challengeId
to the client-side SDK for execution.The email authentication method allows you to onboard users by sending a OTP to their email address. This eliminates the need for them to memorize seed phrases for private key management. Once you initialize a user, Circle creates a wallet for them using multi-party computation (MPC) technology.
The following example UX screens show how a user can be log in with their email address, receive an email containing the OTP verification code in their email inbox, and enter the verification code on the verification screen.
Customize UI
The verification code prompt is predefined by SDK. You can customize UI elements including copy, color, and images. For more, see Web SDK UI Customizations.
Send again
When Send again is selected, the SDK sends you an event to the registered listener. You can then make a request to the POST/users/email/resendOTP
endpoint, which emails the user a new OTP.
Before initializing the SDK:
Once the above conditions are met, you can initialize the SDK.
{{ email.otp }}
{{ email.otp }}
is a dynamic value reserved for the OTP and must be included in the message. If not, users receiving the email will not receive the OTP.
To test how to onboard a user and create a wallet with our sample app on web, see Quickstarts for Social Logins or Email Authentication.
The process for onboarding a user with email onto your application is as follows:
POST
request to the /users/email/token
endpoint with deviceId
included in the request body.otpToken
, deviceToken
, and deviceEncryptionKey
in the response.verifyOTP
,deviceToken
, and deviceEncryptionKey
to the client-side SDK.userId
.userID
, userToken
, encryptionKey
, and refreshToken
.After you've onboarded your user, you can initialize the user and create a wallet. The process is as follows:
POST
request to the/user/initialize
endpoint withuserToken
included in the request body.challengeId
in the response.challengeId
to the client-side SDK for execution.The refresh token concept is for social login and email authentication methods only.
A user token is the session identifier. It automatically expires 14 days after it was generated. Upon expiration, your users are logged out of your application.
To prevent your users from being logged out too frequently, you can include the existing live user token, its corresponding refreshToken
, and a new user token in a POST
request to the /users/token/refresh
endpoint. The new user token is returned in the response.
Users invoke usage of their private keys through their specified PIN code when signing up for your application. The PIN is then used to encrypt and decrypt access to their private keys when creating a transaction on the blockchain. For more, see Quickstarts.
PIN code storage
Your users are ultimately responsible for accessing their wallets. You must ensure they understand the importance of remembering their PIN code and answers to their security questions.
A PIN is a 6-digit code that is chosen by the user and is required to authorize interactions with their wallet. A PIN is encrypted as the user enters it on their device, which ensures no one else has access to their PIN.
Since a PIN is required to access and authorize the movement of assets, it is extremely important that your users remember their PIN codes and never share it with anyone. If a user enters an incorrect PIN more than three times, the PIN is locked for 30 minutes.
If you enable biometrics, your users can authorize signing actions using their fingerprint or facial recognition on their mobile devices. This means a PIN is no longer required for every transaction or signature request. Enabling biometrics enhances security, provides a better user experience, and reduces the likelihood of fraud.
The following example UX screens show how users can authorize a purchase transaction with biometrics.
When signing up for your application, users set up answers to security questions after they specify their PIN. These answers are used in the wallet recovery process.
If users lose or lock their PIN, they can unfreeze their wallets by going through the recovery process. They must answer their chosen security questions correctly. If the user incorrectly answers security questions more than three times, the recovery process locks for 30 minutes.
The following example UX screens show how users can specify a PIN and recovery method during the onboarding process for your application.