Register a passkey

Passkey creation/registration is a three-step process:

1. Authorised in your backend
2. Created in your frontend
3. Verified and linked to an account in your backend

Backend: authorise registration

Your backend needs to authorise the passkey creation. It will generate a registrationToken for use by your frontend:

backend/register.ts

import { Passlock } from "@passlock/server";

// from your development tenancy settings
const passlock = new Passlock({
  tenancyId: "myTenancyId",
  apiKey: "myApiKey"
});

const user = await getCurrentUser();

const result = await passlock.authorizePasskeyRegistration({
  rpId: "example.com", // "localhost" for development
  userId: user.id,
  username: user.email,
  displayName: user.name,
});

if (result.success) {
  // provide this to your frontend code
  // see frontend/register.ts below
  return result.registrationToken;
}

Send only the registrationToken to your frontend. Treat it as a short-lived bearer token for creating one passkey for the user.

Tip

Registration token generation could happen on page render, or in response to a fetch request from your frontend. How you pass the token to the frontend is entirely up to you. Just bear in mind that the token is only valid for 10 minutes.

Frontend: create the passkey

Your frontend code will obtain a registrationToken from your backend, and use it to trigger passkey registration on the device:

frontend/register.ts

import { Passlock } from "@passlock/browser";

const passlock = new Passlock({ tenancyId: "myTenancyId" });

createPasskeyButton.addEventListener("click", async () => {
  // see backend/register.ts above
  const registrationToken = await fetchTokenFromBackend();

  const result = await passlock.registerPasskey({
    registrationToken
  });

  if (result.success) {
    // see backend/register.ts below
    await submitCodeToBackend(result.value.code);
  }
});

The browser success payload includes both an id_token and a code. This quickstart guide uses the code exchange flow. Pass the code to your backend for verification.

Backend: verify the passkey

Exchange the code for details about the passkey:

backend/register.ts

import { Passlock } from "@passlock/server";

// from your development tenancy settings
const passlock = new Passlock({
  tenancyId: "myTenancyId",
  apiKey: "myApiKey"
});

const user = await getCurrentUser();

const result = await passlock.exchangeCode({ code });

if (result.success) {
  // link the passkey to a local user account in your database
  await assignPasskeyToUser(user.id, result.value.authenticatorId);
};