Authenticate a passkey

The process is almost identical to passkey registration. You’ll use the Passlock browser library to trigger passkey login on the device, then send the resulting code to your backend.

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

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

  Frontend->>Backend: code

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

  Backend->>Backend: lookupUser(authenticatorId)

Frontend / Browser

This time you don’t need a username. Passkeys are discoverable, meaning the browser/device will prompt the user to select the passkey they want to sign in with:

Default (safe)

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

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

// call this in a button click handler or similar action
const result = await passlock.authenticatePasskey({});

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 development tenancy settings
const tenancyId = "myTenancyId";
const passlock = new Passlock({ tenancyId });

// call this in a button click handler or similar action
const result = await passlock.authenticatePasskey({});

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

Functions (safe)

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

// get this from your development tenancy settings
const tenancyId = "myTenancyId";

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

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

Functions (unsafe)

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

// get this from your development tenancy settings
const tenancyId = "myTenancyId";

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

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

Choose your code style

As before, submit the code to your backend.

Backend

The process is exactly the same as for the registration flow.

Get the passkey details

The ExtendedPrincipal includes an authenticatorId, which you previously linked to a user account in your backend system. You’ll use this ID to lookup the associated user and log them in.

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

// implement lookupUser to identify a user based on their
// passkey id (authenticatorId)
lookupUser(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
  lookupUser(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 });

// implement lookupUser to identify a user based on their
// passkey id (authenticatorId)
lookupUser(result.authenticatorId);

Choose your code style

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}