Passkey Authentication

Overview

Passkey authentication provides a phishing-resistant, passwordless sign-in experience for guests using WebAuthn / FIDO2. Instead of password or one-time password (OTP), guests authenticate with a platform authenticator (Face ID, Touch ID, Windows Hello) or a roaming authenticator (hardware security key). The private key never leaves the device, making passkeys immune to phishing, credential stuffing, and replay attacks.

Passkey support is integrated into the Guest Identity Service (GIS) and works alongside existing authentication methods (Basic Auth, Advanced Auth OTP, and Social Login). Guests who already sign in with those methods can optionally enroll a passkey for faster future logins.

Your integration work is really two tasks:

• Recognize returning guests who already have a passkey, so you can offer the fast biometric sign-in instead of making them type a password or wait on an OTP.
• Invite guests who don't have one yet to enroll, at the right moment, in a way that is easy to accept and easy to dismiss.

Prerequisites

Before integrating passkeys, ensure the following:

1. Passkeys enabled for the business — The enable_passkeys flag must be set to true in the brand configuration on the Punchh platform. See Program Meta API. Contact your PAR representative if this is not already enabled.
2. Valid OAuth client — You need a doorkeeper application UID (client) with the Advance Auth scope. Contact your PAR representative to enable this platform configuration.
3. Platform support — The brand's mobile app or web browser must support WebAuthn. Perform feature-detection checks before offering passkey options to the guest (see Browser and Platform Support).

How Passkeys Work

Passkeys use public-key cryptography. During registration, the guest's device generates a key pair — the public key is sent to GIS, while the private key stays on the device secured by the platform authenticator. During authentication, GIS sends a challenge, the device signs it with the private key, and GIS verifies the signature using the stored public key.

Two Ceremonies: Registration and Authentication

WebAuthn (the standard behind passkeys) always works in a two-step "ceremony": first the server hands the device a one-time challenge ("options"), then the device signs it and sends back proof ("the credential"). GIS exposes this as two request/response round trips for each direction:

Username-First Sign-In

GIS uses a username-first flow: the guest types their email (or phone) before any biometric prompt appears. This lets GIS look up the right account, apply the right brand's policy, and only then ask the device to show a Face ID / Touch ID / Windows Hello prompt. Practically, this means your login screen keeps its existing "enter email" step — you are adding a decision point after that step, not replacing it.

Two Levels of Availability

There are two independent questions your client needs answered, and they use two different signals:

Get both right and the rest of the integration falls into place naturally. See Brand Configuration Check and Detecting Guest Passkey Status for details.

Key Concepts

Passkey APIs

All endpoints require the client query parameter (Doorkeeper application UID with AdvanceAuth scope).

For full request/response schemas and error examples, see the Passkey API Reference.

Brand Configuration Check

Before showing any passkey-related UI, ask GIS whether the feature is enabled for the current business. Passkeys must be explicitly enabled for each brand in GIS settings. This setting is disabled by default — so this check is not optional, and it should happen early (e.g., at session start, alongside whatever other initial configuration call your mobile or web app already makes).

Passkey Configuration in the Program Meta API Response

The Program Meta API response includes the enable_passkeys, login_mode, and external_idp_enabled parameters. These parameters are also available under the gis object. See Program Meta API

GET /api2/mobile/meta.json?client={client_uid}

{
  "enable_passkeys": true,
  "login_mode": "preferred",       // "preferred" | "optional"
  "external_idp_enabled": true,
  "gis": {
    "passkeys_enabled": true,
    "external_idp_enabled": false,
    "advance_auth_enabled": true,
    "basic_auth_enabled": false,
    "google_enabled": false,
    "apple_enabled": false,
    "facebook_enabled": false
    // ...other brand auth settings
  }
}

Important: Cache this configuration for the session, but re-fetch it on mobile or web relaunch. A brand admin can disable passkey after guests have already registered one — see Edge Cases & Fallback Behavior for what happens to those guests.

Mobile /Web App Decision Logic

1. If enable_passkeys is false , render the login screen exactly as it works today. No passkey copy, no enrollment prompts, no username-first change.
2. If enable_passkeys is true and login_mode is "preferred", proceed to Detecting Guest Passkey Status to check the individual guest, and treat passkey sign-in as the default path once a guest is confirmed to have one; actively surface the post-login enrollment nudge for guests who do not.
3. If enable_passkeys is true and login_mode is "optional" , same checks, but keep passkey positioned as "also available" rather than the lead option — e.g., show it as a secondary button/link rather than pre-selected, and nudge enrollment less assertively (lower frequency, lower visual priority).

Detecting Guest Passkey Status

There is no standalone "has this user got a passkey?" look-up endpoint. Instead, the check is built into the first step of the sign-in ceremony: POST /api2/passkey/authentication_options. You call it with the guest's identifier (email or phone) as soon as they finish typing it on the login screen, and its response tells you everything you need:

Why this design works well for UX: Because the check rides along with the username-first step guests already go through, there is no extra screen, no extra tap, and no visible delay for guests who do not have a passkey — the client simply continues straight into the familiar password/OTP/social flow.

Integration Flows

Passkey Registration (Post-Login Enrollment)

Passkey registration is an authenticated flow. The guest must already be signed in via Basic Auth, Advanced Auth (OTP), or Social Login before enrolling a passkey.

When to Prompt for Registration

Show the passkey enrollment prompt when all of the following conditions are met:

• The brand configuration has enable_passkeys set to true.
• The guest just signed in with a non-passkey method (password, OTP, or social login). Do not make an extra look-up call to check — infer this from the sign-in method used.
• The guest's mobile app or web browser supports passkeys (see Browser and Platform Support). Never show the prompt on an unsupported browser or app version.
• The guest has not dismissed the prompt too recently. Apply a cool-down period so the same guest is not prompted on every login (see Enrollment UX Guidelines).

Step-by-Step

1. Guest completes sign-in via Basic Auth, Advanced Auth (OTP), or Social Login. GIS returns tokens as normal.

2. The mobile or web app evaluates registration conditions. If all conditions pass, show a lightweight, dismissible prompt (for example: "Sign in faster next time — set up Face ID / fingerprint / device PIN."). Include a clear "Not now" or skip action of equal visual weight to "Set up".

3. If the guest accepts, the mobile or web app calls POST /api2/passkey/registration_options with:

   • The guest's Bearer access token (from step 1) in the Authorization header
   • client={client_uid} as a query parameter
   • No request body is needed

4. The mobile or web app passes the returned options to WebAuthn. The response contains challenge, rp (relying party), user, and pubKeyCredParams. Pass these into the platform's WebAuthn navigator.credentials.create() call. The device prompts the guest for biometric or PIN confirmation and generates a new key pair.

5. The mobile or web app sends the attestation to GIS. Post the WebAuthn attestation result to POST /api2/passkey/registration:

   {
     "credential": {
       "id": "BASE64URL-ENCODED_CREDENTIAL_ID_GOES_HERE",
       "type": "public-key",
       "response": {
         "clientDataJSON": "BASE64URL-ENCODED_CLIENT_DATA_JSON_GOES_HERE",
         "attestationObject": "BASE64URL-ENCODED_ATTESTATION_OBJECT_GOES_HERE"
       }
     },
     "label": "My iPhone"
   }
   

   json

   The label field is optional — it provides a human-readable name for the passkey and defaults to "Passkey" when omitted.

6. On success (HTTP 200), show a brief confirmation (for example: "You're all set — next time, just use Face ID") and continue the guest into the app. Do not show the enrollment prompt again for this guest on this device.

7. If the guest taps "Not now", dismiss the prompt immediately with no friction. Do not block or delay navigation into the app.

Registration Options Response

The POST /api2/passkey/registration_options response returns the fields needed to call navigator.credentials.create():

{
  "data": {
    "challenge": "CHALLENGE_GOES_HERE",
    "rp": {
      "id": "loyalty.example.com",
      "name": "Coffee Shop"
    },
    "user": {
      "id": "USER_ID_GOES_HERE",
      "name": "test@example.com",
      "displayName": "DISPLAY_NAME_GOES_HERE"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 }
    ]
  }
}

Passkey Authentication (Sign-In)

Passkey authentication is an unauthenticated flow — no existing tokens are required. The guest provides their email or phone number, and the device performs the biometric/PIN challenge.

Step-by-Step

1. Guest initiates sign-in. The mobile or web app presents a passkey sign-in option alongside other authentication methods.

2. The mobile or web app calls POST /api2/passkey/authentication_options with:

   • client={client_uid} as a query parameter
   • Request body containing the guest's identifier:

     {
       "identifier": "test@example.com"
     }
     

     json
     The identifier can be an email address or a phone number.

3. GIS returns assertion options and a session token. The response contains WebAuthn PublicKeyCredentialRequestOptions plus a one-time session_token:

   {
     "data": {
       "challenge": "CHALLENGE_GOES_HERE",
       "rpId": "loyalty.example.com",
       "allowCredentials": [
         { "type": "public-key", "id": "ID_GOES_HERE" }
       ],
       "session_token": "SESSION_TOKEN_GOES_HERE"
     }
   }
   

   json

   A 200 response means the guest has at least one registered passkey — proceed with the biometric prompt. A 422 with passkey_authentication_not_available means the guest has no passkey for this business — this is the expected common case; silently fall back to password / OTP / social sign-in without surfacing an error.

4. Client passes the options to WebAuthn. Call navigator.credentials.get() with the returned challenge, rpId, and allowCredentials. The device prompts the guest for biometric or PIN verification.

5. Client sends the assertion result to GIS. Post the assertion payload plus the session_token to POST /api2/passkey/authentication:

   {
     "session_token": "SESSION_TOKEN_GOES_HERE",
     "credential": {
       "id": "BASE64URL-ENCODED_CREDENTIAL_ID_GOES_HERE",
       "type": "public-key",
       "response": {
         "clientDataJSON": "BASE64URL-ENCODED_CLIENT_DATA_JSON_GOES_HERE",
         "authenticatorData": "BASE64URL-ENCODED_AUTHENTICATOR_DATA_GOES_HERE",
         "signature": "BASE64URL-ENCODED_SIGNATURE_GOES_HERE"
       }
     }BASE64URL-ENCODED_CLIENT_DATA_JSON_GOES_HERE
   }
   

   json

   The session_token must match the one returned in step 3. Cross-business reuse of session tokens is rejected.

6. On success (HTTP 200), GIS returns JWT access and refresh tokens:

   {
     "data": {
       "access_token": "ACCESS_TOKEN_GOES_HERE",
       "refresh_token": "REFRESH_TOKEN_GOES_HERE",
       "expires_in": 7200
     }
   }
   

   json

   Use these tokens to access downstream APIs (Ordering, Loyalty, etc.) with Authorization: Bearer <access_token>. This is the same token shape returned by every other GIS login method — no downstream integration changes are needed.

7. If the guest cancels the biometric prompt, or the device reports an error → treat it exactly like a cancelled login attempt: return the guest to the sign-in screen with their existing methods still available (see Edge Cases & Fallback Behavior).

Important: The session_token from authentication_options is single-use and scoped to the business that issued it. Do not cache or reuse it across a retry — if the ceremony fails or times out, start over from authentication_options.

Browser and Platform Support

Never show passkey UI (sign-in offer or enrollment nudge) unless the current client can actually complete a WebAuthn ceremony. Checking this client-side avoids dead ends and the need for GIS to know anything about device capability.

Web

if (window.PublicKeyCredential &&
    typeof PublicKeyCredential
      .isUserVerifyingPlatformAuthenticatorAvailable === "function") {
  const supported = await PublicKeyCredential
      .isUserVerifyingPlatformAuthenticatorAvailable();
  // supported === true → safe to show passkey UI
}

This covers current Chrome, Safari, Edge, and Firefox — no browser extension or plug-in install is required for the guest. If the check fails or the API is absent, treat the guest exactly as a pre-passkey guest: no passkey UI at all, standard fallback methods only.

Mobile App

Passkey registration and use require the app to be on the release that ships the passkey SDK/code path. Gate the feature on app version:

• Maintain a minimum-supported-version constant per platform (iOS / Android) for passkey support, sourced from your release notes for the passkey-enabled build.
• On app launch, compare the running app version against that constant before evaluating any passkey eligibility from the brand configuration check, guest passkey detection, or registration prompt logic.
• Guests on older app versions should see zero difference in their experience — they keep using Basic Auth, Advanced Auth, or Social Login exactly as they do today. Do not show an error, broken button, or partial passkey UI.

Recommendation: It is strongly recommended to pair this with an app-update prompt (banner/nudge, not a hard block) once passkeys roll out broadly, so guests on old versions have a path to the new experience.

Error Handling

All passkey error responses follow the standard GIS error format:

{
  "errors": {
    "error_key": ["Human-readable error message."]
  }
}

The errors below are grouped by how your client should react — use these groupings to build one shared error handler rather than bespoke logic per endpoint.

Silent Fallback — Never Show a Passkey-Specific Error

These are expected, common cases. Continue straight into the guest's normal sign-in flow with no visible error.

Recoverable — Restart the Ceremony

These are transient or timing issues. Retry automatically before surfacing anything to the guest.

User-Facing Message Required

Show a message, but keep it non-technical.

Treat as Success

Full Error Code Reference

Enrollment UX Guidelines

These are the practices that make the difference between guests loving the passkey experience and guests feeling nagged. They apply on top of the mechanics in the integration flows above.

Practices to Avoid

Suggested Enrollment UI Text

Edge Cases & Fallback Behavior

Testing Checklist

Use this before sign-off. Each row should be verified on at least one supported mobile platform and one supported browser.

Support and Escalation

For questions on this guide, endpoint behavior, or brand configuration:

• API / schema questions: Refer to the GIS API documentation — it is the source of truth for exact field names and error codes.
• Brand configuration (enabling Passkeys, login mode, allowed origins, Relying Party ID): Business admins configure this in GIS settings. Contact your PAR representative to update this platform configuration.
• Bugs or unexpected error responses: Include the endpoint, client UID, and full error payload (error key + message) when reporting — this is the fastest path to a resolution.