Register a passkey

You’ll use the Passlock browser library in your frontend to register a passkey on the user’s device. The library will return an id_token and code. You will use the Passlock server library to exchange the code or id_token for details about the new passkey. You will then link the Passkey ID to a local user account in your backend.

sequenceDiagram
  participant Frontend
  participant Browser as @passlock/browser
  participant Backend
  participant Server as @passlock/server

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

  Frontend->>Backend: code

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

  Backend->>Backend: linkPasskey(authenticatorId)

Code styles

We offer 4 variants of the @passlock/browser and @passlock/server functions

1. Default (safe) - A class with methods that don’t throw for expected errors
2. Unsafe - A class with methods that throw
3. Functions (safe) - Standalone functions that don’t throw for expected errors
4. Functions (unsafe) - Standalone functions that throw

We recommend the Default (safe) style. The standalone functions are useful if tree-shakeability is important to you. Read more about the coding style options.

Frontend / Browser

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 (safe)

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

// get this from your dev tenancy settings in the Passlock console
const tenancyId = "myTenancyId";
const passlock = new Passlock({ tenancyId });

// 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 passlock.registerPasskey({ username });

if (result.success) {
  // send this to your backend
  console.log({ code: result.value.code });
} else {
  console.error(result.error.message);
}

Unsafe

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

// get this from your dev tenancy settings in the Passlock console
const tenancyId = "myTenancyId";
const passlock = new Passlock({ tenancyId });

// 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 passlock.registerPasskey({ username });

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

Functions (safe)

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

// 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({ username }, { tenancyId });

if (result.success) {
  // send this to your backend
  console.log({ code: result.value.code });
} else {
  console.error(result.error.message);
}

Functions (unsafe)

import { registerPasskey } from "@passlock/browser/unsafe";

// 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({ username }, { tenancyId });

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

Choose your code style

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 should exchange the code for details about the new 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 (safe)

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

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

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

if (result.success) {
  // implement this
  linkPasskey(user.id, result.value.authenticatorId);
} else {
  console.error(result.error.message);
}

Unsafe

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

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

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

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

Functions (safe)

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 });

if (result.success) {
  // implement this
  linkPasskey(user.id, result.value.authenticatorId);
} else {
  console.error(result.error.message);
}

Functions (unsafe)

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

// 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);

Choose your code style

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

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"

Tip

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}