Passkey - Privy docs

Privy offers the ability to sign up and log users in using a passkey. This lets users access their account simply and securely.

Use loginWithPasskey from the useLoginWithPasskey hook to trigger the passkey login flow.

loginWithPasskey: ({ passkey?: string }) => void

passkey

string

Optionally prompt the user to sign in with a specific passkey credential.

Usage

import { useLoginWithPasskey } from '@privy-io/react-auth';

export default function LoginWithPasskey() {
  const { loginWithPasskey } = useLoginWithPasskey();

  return (
    <div>
      <button onClick={loginWithPasskey}>Log in with passkey</button>
    </div>
  );
}

Use signupWithPasskey from the useSignupWithPasskey hook to trigger the passkey signup flow.

signupWithPasskey: () => void

Usage

import { useSignupWithPasskey } from '@privy-io/react-auth';

export default function SignupWithPasskey() {
  const { signupWithPasskey } = useSignupWithPasskey();

  return (
    <div>
      <button onClick={signupWithPasskey}>Sign up with passkey</button>
    </div>
  );
}

Tracking Flow State

Track the state of the passkey flow via the state variable returned by both the useLoginWithPasskey and useSignupWithPasskey hooks.

state:
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'generating-challenge'}
  | {status: 'awaiting-passkey'}
  | {status: 'submitting-response'}
  | {status: 'done'};

status

The current state of the passkey flow.

error

Error | null

The error that occurred during the passkey flow.

Callbacks

You can optionally pass callbacks into the useLoginWithPasskey and useSignupWithPasskey hooks to run custom logic after a successful login or signup, or to handle errors that occur during the flow.

`onComplete`

onComplete: ({user, isNewUser, wasAlreadyAuthenticated, loginMethod, linkedAccount}) => void

Parameters

User

PrivyUser

The user object returned after successful login or signup.”

isNewUser

boolean

Whether the user is a new user or an existing user.

wasAlreadyAuthenticated

boolean

Whether the user was already authenticated before the passkey flow.

The login method used to authenticate the user.

linkedAccount

LinkedAccount

The linked account if the user was already authenticated.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the passkey flow.

Use loginWithPasskey from the useLoginWithPasskey hook to trigger the passkey login flow.

loginWithPasskey: ({ passkey?: string }) => void

passkey

string

Optionally prompt the user to sign in with a specific passkey credential.

Usage

import { useLoginWithPasskey } from '@privy-io/react-auth';

export default function LoginWithPasskey() {
  const { loginWithPasskey } = useLoginWithPasskey();

  return (
    <div>
      <button onClick={loginWithPasskey}>Log in with passkey</button>
    </div>
  );
}

Use signupWithPasskey from the useSignupWithPasskey hook to trigger the passkey signup flow.

signupWithPasskey: () => void

Usage

import { useSignupWithPasskey } from '@privy-io/react-auth';

export default function SignupWithPasskey() {
  const { signupWithPasskey } = useSignupWithPasskey();

  return (
    <div>
      <button onClick={signupWithPasskey}>Sign up with passkey</button>
    </div>
  );
}

Tracking Flow State

Track the state of the passkey flow via the state variable returned by both the useLoginWithPasskey and useSignupWithPasskey hooks.

state:
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'generating-challenge'}
  | {status: 'awaiting-passkey'}
  | {status: 'submitting-response'}
  | {status: 'done'};

status

The current state of the passkey flow.

error

Error | null

The error that occurred during the passkey flow.

Callbacks

`onComplete`

onComplete: ({user, isNewUser, wasAlreadyAuthenticated, loginMethod, linkedAccount}) => void

Parameters

User

PrivyUser

The user object returned after successful login or signup.”

isNewUser

boolean

Whether the user is a new user or an existing user.

wasAlreadyAuthenticated

boolean

Whether the user was already authenticated before the passkey flow.

The login method used to authenticate the user.

linkedAccount

LinkedAccount

The linked account if the user was already authenticated.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the passkey flow.

Follow the passkeys setup guide to enable passkey authentication in your React Native app.

Use loginWithPasskey from the useLoginWithPasskey hook to authenticate users using a passkey. Before using this method, ensure you have setup passkeys as described in this guide.

loginWithPasskey: ({ relyingParty: string }) => Promise<PrivyUser>

Parameters

relyingParty

string

required

The URL origin where your Apple App Site Association or Digital Asset Links are available (e.g. https://example.com).

Response

user

PrivyUser

The user object returned after successful login.

string

The Privy DID which you may use to identify your user on your backend

created_at

number

UNIX timestamp of when the user was created

linked_accounts

Array

An array of the user's linked accounts

AppleAccount

Object

type

string

'apple_oauth'

string

Email address associated with the user's Apple account

subject

number

ID of user from Apple's user API

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

CustomJwtAccount

Object

type

string

'custom_auth'

custom_user_id

string

ID of user from custom auth provider

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

DiscordAccount

Object

type

string

'discord_oauth'

subject

string

ID of user from Discord user API response

string

Email of user from Discord user API response

username

string

Username of user from Discord user API response, including the 4-digit discriminator prefixed by '#'

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

EmailAccount

Object

type

string

'email'

address

string

Email address of user account

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

FarcasterAccount

Object

type

string

'farcaster'

fid

number

FID of the user from Farcaster user API response

owner_address

string

Wallet address of the user from Farcaster user API response (Farcaster wallet address, not Privy embedded wallet address)

username

string

Username of user from Farcaster user API response (does not include the '@')

display_name

string

Display name of user from Farcaster user API response

bio

string

Bio of user from Farcaster user API response

profile_picture_url

string

Profile picture URL of the user from Farcaster user API response

homepage_url

string

Profile URL of the user from Farcaster user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GithubAccount

Object

type

string

'github_oauth'

subject

string

ID of user from GitHub user API response

string

Email of user from GitHub user API response

name

string

Name of user from GitHub user API response

username

string

Username of user from GitHub user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GoogleAccount

Object

type

string

'google_oauth'

subject

string

'sub' pulled from Google-provided JWT with "openid" scope

string

'email' from Google-provided JWT with "email" scope

name

string

'name' from Google-provided JWT with "profile" scope

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

InstagramAccount

Object

type

string

'instagram_oauth'

subject

string

ID of user from Instagram user API response

username

string

The name displayed on a user's profile from Instagram's `/me` API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

LinkedinAccount

Object

type

string

'linkedin_oauth'

subject

string

ID of user from LinkedIn user API response

string

Email of user from LinkedIn user API response

name

string

Name of user from LinkedIn user API response (does not include the '@')

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

PhoneAccount

Object

type

string

'phone'

number

string

Phone number of user account (non-international numbers default to US)

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

SpotifyAccount

Object

type

string

'spotify_oauth'

subject

string

ID of user from Spotify user API response

string

Email of user from Spotify user API

name

string

The name displayed on a user's profile from Spotify display_name API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TelegramAccount

Object

type

string

'telegram'

telegram_user_id

string

ID of a user's telegram account

first_name

string

The first name displayed on a user's telegram account

last_name

string

The last name displayed on a user's telegram account

username

string

The username displayed on a user's telegram account

photo_url

string

The url of a user's telegram account profile picture

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TwitterAccount

Object

type

string

'twitter_oauth'

subject

string

ID of user from Twitter user API response

name

string

Name of user from Twitter user API response

username

string

Username of user from Twitter user API response (does not include the '@')

profile_picture_url

string

Profile picture URL of the user from Twitter user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

WalletAccount

Object

type

string

'wallet'

chain_type

string

Type of chain for the wallet: 'ethereum' or 'solana'

address

string

Checksummed wallet address

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

Usage

import {useLoginWithPasskey} from '@privy-io/expo/passkey';

export function LoginButton() {
  const {loginWithPasskey} = useLoginWithPasskey();

  return (
    <Button onPress={() => loginWithPasskey({relyingParty: '<your-applications-relying-party>'})}>
      Login
    </Button>
  );
}

Use signupWithPasskey from the useSignupWithPasskey hook to sign up users using a passkey.

signupWithPasskey: ({ relyingParty: string }) => Promise<PrivyUser>

Parameters

relyingParty

string

required

The URL origin where your Apple App Site Association or Digital Asset Links are available (e.g. https://example.com).

Response

user

PrivyUser

The user object returned after successful signup.

string

The Privy DID which you may use to identify your user on your backend

created_at

number

UNIX timestamp of when the user was created

linked_accounts

Array

An array of the user's linked accounts

AppleAccount

Object

type

string

'apple_oauth'

string

Email address associated with the user's Apple account

subject

number

ID of user from Apple's user API

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

CustomJwtAccount

Object

type

string

'custom_auth'

custom_user_id

string

ID of user from custom auth provider

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

DiscordAccount

Object

type

string

'discord_oauth'

subject

string

ID of user from Discord user API response

string

Email of user from Discord user API response

username

string

Username of user from Discord user API response, including the 4-digit discriminator prefixed by '#'

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

EmailAccount

Object

type

string

'email'

address

string

Email address of user account

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

FarcasterAccount

Object

type

string

'farcaster'

fid

number

FID of the user from Farcaster user API response

owner_address

string

Wallet address of the user from Farcaster user API response (Farcaster wallet address, not Privy embedded wallet address)

username

string

Username of user from Farcaster user API response (does not include the '@')

display_name

string

Display name of user from Farcaster user API response

bio

string

Bio of user from Farcaster user API response

profile_picture_url

string

Profile picture URL of the user from Farcaster user API response

homepage_url

string

Profile URL of the user from Farcaster user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GithubAccount

Object

type

string

'github_oauth'

subject

string

ID of user from GitHub user API response

string

Email of user from GitHub user API response

name

string

Name of user from GitHub user API response

username

string

Username of user from GitHub user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GoogleAccount

Object

type

string

'google_oauth'

subject

string

'sub' pulled from Google-provided JWT with "openid" scope

string

'email' from Google-provided JWT with "email" scope

name

string

'name' from Google-provided JWT with "profile" scope

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

InstagramAccount

Object

type

string

'instagram_oauth'

subject

string

ID of user from Instagram user API response

username

string

The name displayed on a user's profile from Instagram's `/me` API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

LinkedinAccount

Object

type

string

'linkedin_oauth'

subject

string

ID of user from LinkedIn user API response

string

Email of user from LinkedIn user API response

name

string

Name of user from LinkedIn user API response (does not include the '@')

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

PhoneAccount

Object

type

string

'phone'

number

string

Phone number of user account (non-international numbers default to US)

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

SpotifyAccount

Object

type

string

'spotify_oauth'

subject

string

ID of user from Spotify user API response

string

Email of user from Spotify user API

name

string

The name displayed on a user's profile from Spotify display_name API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TelegramAccount

Object

type

string

'telegram'

telegram_user_id

string

ID of a user's telegram account

first_name

string

The first name displayed on a user's telegram account

last_name

string

The last name displayed on a user's telegram account

username

string

The username displayed on a user's telegram account

photo_url

string

The url of a user's telegram account profile picture

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TwitterAccount

Object

type

string

'twitter_oauth'

subject

string

ID of user from Twitter user API response

name

string

Name of user from Twitter user API response

username

string

Username of user from Twitter user API response (does not include the '@')

profile_picture_url

string

Profile picture URL of the user from Twitter user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

WalletAccount

Object

type

string

'wallet'

chain_type

string

Type of chain for the wallet: 'ethereum' or 'solana'

address

string

Checksummed wallet address

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

Usage

import {useSignupWithPasskey} from '@privy-io/expo/passkey';

export function SignupButton() {
  const {signupWithPasskey} = useSignupWithPasskey();

  return (
    <Button onPress={() => signupWithPasskey({relyingParty: '<your-applications-relying-party>'})}>
      Signup
    </Button>
  );
}

Tracking Flow State

Track the state of the passkey flow via the state variable returned by both the useLoginWithPasskey and useSignupWithPasskey hooks.

state:
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'generating-challenege'}
  | {status: 'awaiting-passkey'}
  | {status: 'submitting-response'}
  | {status: 'done'};

status

The current state of the passkey flow.

error

Error | null

The error that occurred during the passkey flow.

Callbacks

`onSuccess`

onSuccess: (user: PrivyUser, isNewUser: boolean) => Promise<void>

Parameters

user

PrivyUser

The user object returned after successful login or signup.

string

The Privy DID which you may use to identify your user on your backend

created_at

number

UNIX timestamp of when the user was created

linked_accounts

Array

An array of the user's linked accounts

AppleAccount

Object

type

string

'apple_oauth'

string

Email address associated with the user's Apple account

subject

number

ID of user from Apple's user API

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

CustomJwtAccount

Object

type

string

'custom_auth'

custom_user_id

string

ID of user from custom auth provider

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

DiscordAccount

Object

type

string

'discord_oauth'

subject

string

ID of user from Discord user API response

string

Email of user from Discord user API response

username

string

Username of user from Discord user API response, including the 4-digit discriminator prefixed by '#'

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

EmailAccount

Object

type

string

'email'

address

string

Email address of user account

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

FarcasterAccount

Object

type

string

'farcaster'

fid

number

FID of the user from Farcaster user API response

owner_address

string

Wallet address of the user from Farcaster user API response (Farcaster wallet address, not Privy embedded wallet address)

username

string

Username of user from Farcaster user API response (does not include the '@')

display_name

string

Display name of user from Farcaster user API response

bio

string

Bio of user from Farcaster user API response

profile_picture_url

string

Profile picture URL of the user from Farcaster user API response

homepage_url

string

Profile URL of the user from Farcaster user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GithubAccount

Object

type

string

'github_oauth'

subject

string

ID of user from GitHub user API response

string

Email of user from GitHub user API response

name

string

Name of user from GitHub user API response

username

string

Username of user from GitHub user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

GoogleAccount

Object

type

string

'google_oauth'

subject

string

'sub' pulled from Google-provided JWT with "openid" scope

string

'email' from Google-provided JWT with "email" scope

name

string

'name' from Google-provided JWT with "profile" scope

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

InstagramAccount

Object

type

string

'instagram_oauth'

subject

string

ID of user from Instagram user API response

username

string

The name displayed on a user's profile from Instagram's `/me` API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

LinkedinAccount

Object

type

string

'linkedin_oauth'

subject

string

ID of user from LinkedIn user API response

string

Email of user from LinkedIn user API response

name

string

Name of user from LinkedIn user API response (does not include the '@')

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

PhoneAccount

Object

type

string

'phone'

number

string

Phone number of user account (non-international numbers default to US)

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

SpotifyAccount

Object

type

string

'spotify_oauth'

subject

string

ID of user from Spotify user API response

string

Email of user from Spotify user API

name

string

The name displayed on a user's profile from Spotify display_name API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TelegramAccount

Object

type

string

'telegram'

telegram_user_id

string

ID of a user's telegram account

first_name

string

The first name displayed on a user's telegram account

last_name

string

The last name displayed on a user's telegram account

username

string

The username displayed on a user's telegram account

photo_url

string

The url of a user's telegram account profile picture

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

TwitterAccount

Object

type

string

'twitter_oauth'

subject

string

ID of user from Twitter user API response

name

string

Name of user from Twitter user API response

username

string

Username of user from Twitter user API response (does not include the '@')

profile_picture_url

string

Profile picture URL of the user from Twitter user API response

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

WalletAccount

Object

type

string

'wallet'

chain_type

string

Type of chain for the wallet: 'ethereum' or 'solana'

address

string

Checksummed wallet address

first_verified_at

number

UNIX timestamp for when the account was first verified and linked to the user

latest_verified_at

number

UNIX timestamp for when the account was last verified

isNewUser

boolean

Whether the user is a new user or an existing user.

Usage

import {useLoginWithPasskey} from '@privy-io/expo/passkey';

export function LoginScreen() {
  const {loginWithPasskey} = useLoginWithPasskey({
    onSuccess(user, isNewUser) {
      // show a toast, send analytics event, etc...
    },
  });

  // ...
}

`onError`

onError: (error: Error) => Promise<void>

Parameters

error

Error

The error that occurred during the passkey flow.

Usage

import {useLoginWithPasskey} from '@privy-io/expo/passkey';

export function LoginScreen() {
  const {loginWithPasskey} = useLoginWithPasskey({
    onError(error) {
      // show a toast, update form errors, etc...
    },
  });

  // ...
}

User authentication

​Login with Passkey

​Usage

​Sign up with Passkey

​Usage

​Tracking Flow State

​Callbacks

​onComplete

​Parameters

​onError

​Parameters

​Login with Passkey

​Usage

​Sign up with Passkey

​Usage

​Tracking Flow State

​Callbacks

​onComplete

​Parameters

​onError

​Parameters

​Login with Passkey

​Parameters

​Response

​Usage

​Sign up with Passkey

​Parameters

​Response

​Usage

​Tracking Flow State

​Callbacks

​onSuccess

​Parameters

​Usage

​onError

​Parameters

​Usage

Login with Passkey

Usage

Sign up with Passkey

Usage

Tracking Flow State

Callbacks

`onComplete`

Parameters

`onError`

Parameters

Login with Passkey

Usage

Sign up with Passkey

Usage

Tracking Flow State

Callbacks

`onComplete`

Parameters

`onError`

Parameters

Login with Passkey

Parameters

Response

Usage

Sign up with Passkey

Parameters

Response

Usage

Tracking Flow State

Callbacks

`onSuccess`

Parameters

Usage

`onError`

Parameters

Usage