Register a passkey

You’ll use the Passlock client library in your frontend to register a passkey on the user’s device. The library will return an id_token and code, which you will exchange for details about the newly created passkey. You will then link the Passkey ID to a local user account in your backend.

sequenceDiagram
  participant Frontend
  participant Client as @passlock/client
  participant Backend
  participant Server as @passlock/server

  Frontend->>Client: registerPasskey()
  Client-->>Frontend: id_token, code

  Frontend->>Backend: code

  Backend->>Server: exchangeCode(code)
  Server-->>Backend: authenticatorId
  
  Backend->>Backend: linkPasskey(authenticatorId)

TIP - 'safe' variants

When you import from @passlock/client or @passlock/server you’ll get “unsafe” functions i.e. functions that can throw. Alternatively you can import from @passlock/client/safe or @passlock/server/safe to get “safe” functions, which return discriminated unions composed of a success or error. Read more about safe vs unsafe functions.

Frontend

You’ll need a username to register a passkey. How you obtain this is up to you, if the user is already signed into your system you could use their account name, otherwise you’d capture a username during your registration flow. For now we’ll hardcode it:

Default

import { registerPasskey } from "@passlock/client";

// get this from your dev tenancy settings in the Passlock console
const tenancyId = "myTenancyId";

// capture in a form or prefill if the user is already logged in
const username = "jdoe@example.com";

// call this in a button click handler or similar action
const result = await registerPasskey({ tenancyId, username });

// send this to your backend for verification
console.log({ code: result.code });

Safe

import {
  registerPasskey,
  isRegistrationSuccess
} from "@passlock/client/safe";

// get this from your dev tenancy settings in the Passlock console
const tenancyId = "myTenancyId";

// capture in a form or prefill if the user is already logged in
const username = "jdoe@example.com";

// call this in a button click handler or similar action
const result = await registerPasskey({ tenancyId, username });

// narrow the type down to a RegistrationSuccess
if (isRegistrationSuccess(result)) {
  // send this to your backend
  console.log({ code: result.code });
} else {
  // TS will infer a RegistrationError
  console.error(result.message);
}

Assuming everything went well, you’ll obtain an id_token (JWT) and code. For now we’ll use the code. Submit it to your backend by whichever means you prefer (form submission, fetch, URL redirect etc.)

Backend

Your backend needs to exchange the code for details about the newly created passkey.

Get the passkey details

We’ll use the @passlock/server library to do this, but you can also make a vanilla REST call

Default

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

// get these from your development tenancy settings
const tenancyId = "myTenancyId";
const apiKey = "myApiKey";

const result = await exchangeCode({ code, tenancyId, apiKey });

// result includes details about the passkey. implement
// linkPasskey to associate the passkey with a local user id
linkPasskey(user.id, result.authenticatorId);

Safe

import { exchangeCode, isExtendedPrincipal } from "@passlock/server/safe";

// get these from your development tenancy settings
const tenancyId = "myTenancyId";
const apiKey = "myApiKey";

const result = await exchangeCode({ code, tenancyId, apiKey });

// narrow the type down to an ExtendedPrincipal (successful outcome)
if (isExtendedPrincipal(result)) {
  // implement this
  linkPasskey(user.id, result.authenticatorId);
} else {
  // TS will infer the error type
  console.error(result.message);
}

exchangeCode returns an ExtendedPrincipal, representing a successful registration or authentication operation. Extended principal includes an authenticatorId property (passkeyId).

Associate the passkey with a user

You’ll need to link the ExtendedPrincipal.authenticatorId to a user account in your backend system. When the user signs in with the passkey you’ll identify their account using the same authenticatorId

---
title: Example table structure
---
erDiagram
  user[user] {
    int id PK
  }
  authenticator[authenticator] {
    string authenticatorId PK "returned by exchangeCode"
    int userId FK "points to user.id"
  }
  user ||--|{ authenticator : "User has one or more authenticators"

Caution

The Principal also includes a userId, but for now you should avoid using this, and instead link the authenticatorId (passkey ID) to your local user account. Read more about account linking

Using the REST API

If you’re unable to use the @passlock/server library, you can make a simple REST call:

GET /{tenancyId}/principal/{code} HTTP/1.1
Host: https://api.passlock.dev
Accept: application/json
Authorization: Bearer {apiKey}