Supabase.Auth.Passkey (supabase_auth v1.1.0)

View Source

Passkey (first-factor WebAuthn) operations for Supabase Auth.

Passkeys are an experimental GoTrue feature and must be enabled server-side on your project.

This module covers only the HTTP half of the WebAuthn flow: fetching challenge options from the server and verifying the resulting credential. The WebAuthn ceremony itself (navigator.credentials.create/get) runs in the browser and is wired by your application, typically through a LiveView plus a JavaScript hook. See pages/passkey_guide.md for a complete recipe.

Typical flow

  1. start_registration/2 (or start_authentication/2 for sign-in) fetches the server's WebAuthn options and a challenge_id.
  2. Your app hands the options map to a browser JS hook, which runs the navigator.credentials ceremony.
  3. The hook returns the serialized credential; your app calls verify_registration/4 (or verify_authentication/3), passing the credential through verbatim.

Summary

Functions

delete(client, session, passkey_id)

Removes a passkey from the authenticated user's account.

list(client, session)

Lists the authenticated user's passkeys.

start_authentication(client, opts \\ %{})

Gets WebAuthn authentication options for sign-in with a passkey.

start_registration(client, session)

Gets WebAuthn registration options for the authenticated user.

update(client, session, passkey_id, friendly_name)

Renames a passkey.

verify_authentication(client, challenge_id, credential)

Verifies a passkey sign-in with the browser credential.

verify_registration(client, session, challenge_id, credential)

Verifies a passkey registration with the browser credential.

Functions

delete(client, session, passkey_id)

@spec delete(Supabase.Client.t(), Supabase.Auth.Session.t(), String.t()) ::
  :ok | {:error, term()}

Removes a passkey from the authenticated user's account.

Parameters

  • client - The Supabase client
  • session - Active user session containing access token
  • passkey_id - The passkey to delete

Returns

  • :ok - Passkey deleted
  • {:error, error} - Deletion failed

list(client, session)

@spec list(Supabase.Client.t(), Supabase.Auth.Session.t()) ::
  {:ok, [Supabase.Auth.Passkey.Behaviour.passkey()]} | {:error, term()}

Lists the authenticated user's passkeys.

Parameters

  • client - The Supabase client
  • session - Active user session containing access token

Returns

  • {:ok, passkeys} - List of passkey maps
  • {:error, error} - Request failed

start_authentication(client, opts \\ %{})

@spec start_authentication(Supabase.Client.t(), map()) ::
  {:ok, Supabase.Auth.Passkey.Behaviour.request_options()} | {:error, term()}

Gets WebAuthn authentication options for sign-in with a passkey.

Does not require an authenticated session. When the project has captcha enabled, pass %{captcha_token: "..."}.

Parameters

  • client - The Supabase client
  • opts - Optional map with captcha_token

Returns

  • {:ok, options} - Map with challenge_id, options (WebAuthn request options, passthrough) and optional expires_at
  • {:error, error} - Request failed

start_registration(client, session)

@spec start_registration(Supabase.Client.t(), Supabase.Auth.Session.t()) ::
  {:ok, Supabase.Auth.Passkey.Behaviour.creation_options()} | {:error, term()}

Gets WebAuthn registration options for the authenticated user.

The returned options map must be passed to the browser ceremony; see the passkey guide for a LiveView + JS hook recipe.

Parameters

  • client - The Supabase client
  • session - Active user session containing access token

Returns

  • {:ok, options} - Map with challenge_id, options (WebAuthn creation options, passthrough) and optional expires_at
  • {:error, error} - Request failed

update(client, session, passkey_id, friendly_name)

@spec update(Supabase.Client.t(), Supabase.Auth.Session.t(), String.t(), String.t()) ::
  {:ok, Supabase.Auth.Passkey.Behaviour.passkey()} | {:error, term()}

Renames a passkey.

Parameters

  • client - The Supabase client
  • session - Active user session containing access token
  • passkey_id - The passkey to rename
  • friendly_name - The new friendly name (max 120 characters)

Returns

  • {:ok, passkey} - The updated passkey
  • {:error, error} - Update failed

verify_authentication(client, challenge_id, credential)

@spec verify_authentication(
  Supabase.Client.t(),
  String.t(),
  Supabase.Auth.Passkey.Behaviour.credential()
) :: {:ok, Supabase.Auth.Session.t()} | {:error, term()}

Verifies a passkey sign-in with the browser credential.

Does not require an authenticated session. On success returns a fresh Supabase.Auth.Session for the user.

Parameters

  • client - The Supabase client
  • challenge_id - The challenge id from start_authentication/2
  • credential - The browser credential map (sent through verbatim)

Returns

  • {:ok, session} - The authenticated session
  • {:error, error} - Verification failed

verify_registration(client, session, challenge_id, credential)

@spec verify_registration(
  Supabase.Client.t(),
  Supabase.Auth.Session.t(),
  String.t(),
  Supabase.Auth.Passkey.Behaviour.credential()
) :: {:ok, Supabase.Auth.Passkey.Behaviour.passkey()} | {:error, term()}

Verifies a passkey registration with the browser credential.

The credential map is the serialized WebAuthn credential (RegistrationResponseJSON) and is sent through verbatim.

Parameters

  • client - The Supabase client
  • session - Active user session containing access token
  • challenge_id - The challenge id from start_registration/2
  • credential - The browser credential map

Returns

  • {:ok, passkey} - The registered passkey
  • {:error, error} - Verification failed