Skip to main content
Circle provides several authentication mechanisms so you can build a familiar onboarding experience. Choose social logins, email, or PIN and security questions to authenticate users and create user-controlled wallets.
  • Social logins: Users sign in with Google, Apple, or Facebook (OAuth 2.0).
  • Email: Send a one-time password (OTP) by email for identity verification.
  • PIN: Users set a PIN to authorize transactions; optional biometrics for fingerprint or face.

​
Authentication type differences

TypeOnboardingSigningKey management
SocialUser is redirected to the provider (Google, Apple, Facebook) to choose the account and sign in. Circle creates the wallet after authentication.When the user sends a transaction or signs, Circle can show UIs to preview and confirm (customizable or disable). See Confirmation UIs.; a key share stays on the user side. Signing happens only when the user acts from their app or device.
EmailUser enters email; Circle sends an OTP. User verifies identity by entering the code.Same as social: when the user sends or signs, Circle can show preview/confirm UIs (customizable or disable).Same as social: 2-of-2 MPC, user-held share; signing only when user acts.
PINUser sets a 6-digit PIN and answers to security questions during signup.No built-in transaction UIs. User previews the request elsewhere, then confirms by entering PIN or using biometrics (if enabled).User has sole access to their keys. PIN (or biometrics) authorizes every transaction.
For key management details, see Key management. For signing UI options, see Confirmation UIs.

​
Social logins

Users sign in with Google, Facebook, or Apple; Circle creates a wallet for them.
Additional social providers: To offer another provider, request it via Circle on Discord.

​
Create a wallet with social logins

  1. Obtain provider IDs: Google Client ID, Facebook App ID, Apple App/Service ID.
  2. In Circle Developer Console, go to Configurator > Authentication Methods > Social Logins and add the IDs.
  3. Keep your app’s ID settings and the Console in sync.
Full walkthrough: Create user wallets with social login.
Important:
  • Circle cannot recover lost credentials or unblock accounts for social logins. Users must contact the respective social provider directly. Recovering a banned Facebook account can take weeks.
  • Each social account (Google, Apple, Facebook) links to one unique user ID. Signing up with multiple providers (for example, Google then Apple) creates separate user IDs.

​
User onboarding with social logins

  1. POST /users/social/token with deviceId → receive deviceToken and deviceEncryptionKey.
  2. Invoke the client-side SDK performLogin with deviceToken and deviceEncryptionKey.
  3. Circle runs the social login flow and returns userID, userToken, encryptionKey, refreshToken, and OAuthInfo.
After onboarding, initialize the user and create a wallet. Steps are the same for social and email; see Initialize user and create wallet (social and email) below.

​
Email

Users sign up with their email; Circle sends an OTP and creates a wallet for them after verification.
Customize UI: The OTP prompt is predefined; you can customize copy, colors, and images. See Web SDK UI Customizations.Send again: When the user taps Send again, the SDK emits an event; call POST /users/email/resendOTP to send a new OTP.

​
Create a wallet with email

  1. In Circle Developer Console, go to Wallets > User Controlled > Configurator > Email.
  2. Enter SMTP credentials (stored encrypted).
  3. Set From, Subject, and Email Template; include {{ email.otp }} in the template.
  4. Use SEND TEST EMAIL to verify.
Full walkthrough: Create user wallets with email.
{{ email.otp }}: This placeholder must appear in the email template so users receive the OTP.

​
User onboarding with email

  1. POST /users/email/token with deviceId → receive otpToken, deviceToken, deviceEncryptionKey.
  2. Your SMTP sends the OTP email to the user.
  3. Pass verifyOTP, deviceToken, and deviceEncryptionKey to the client-side SDK; user enters OTP.
  4. Circle validates and returns userID, userToken, encryptionKey, and refreshToken.

​
Initialize user and create wallet (social and email)

After onboarding (social or email), initialize the user and create a wallet:
  1. POST /user/initialize with userToken in the body.
  2. Circle returns challengeId.
  3. Pass challengeId to the client-side SDK to create the Web3 wallet.

​
User token and refresh token

User and refresh tokens apply to email (and social logins; not PIN). Same token and refresh behavior applies to social logins. The user token is the session identifier and expires 14 days after generation; users are then logged out. To avoid frequent logouts, send a POST request to /users/token/refresh with the existing user token, its refreshToken, and a new user token; the response returns the new user token.

​
PIN

Users set a 6-digit PIN (and optional security questions) to authorize transactions. Keys are held by the user. Optional biometrics allow signing with fingerprint or face on supported devices.
PIN and security questions: Users are responsible for remembering their PIN and security answers. Ensure they understand this; lost PIN and answers can mean lost access.

​
About PIN

The PIN is encrypted on the user’s device. It is required to authorize wallet actions. After three incorrect attempts, the PIN locks for 30 minutes.

​
Biometrics

When enabled, users can approve signing with fingerprint or facial recognition so a PIN is not required every time.

​
Wallet recovery through security questions

Users set security-question answers during signup. If they lose or lock their PIN, they can recover by answering those questions. After three incorrect recovery answers, recovery locks for 30 minutes.
Full walkthrough: Create user wallets with PIN. To restore access after a lost PIN: Recover an account.