Using the REST API

Passlock includes a REST API, along with the @passlock/server library to manage your tenancy data. The REST API allows you to:

• Create, inspect, verify, and delete mailbox challenges for email one-time code flows
• Exchange a passkey registration or authentication code for an ExtendedPrincipal
• List passkeys in your vault
• Fetch a passkey from your vault
• Delete a passkey from your vault
• Update a passkey in your vault
• Prepare and complete passkey registration and authentication operations

Note

The REST API should be used to manage the server-side passkey and mailbox challenge components. For client-side (local device) management, use the @passlock/browser package.

Tenancy ID

REST API calls operate on a specific tenancy. You will need your Tenancy ID, along with the relevant API Key. API endpoints are typically prefixed with the Tenancy ID, e.g.

HTTP

GET https://api.passlock.dev/v2/{tenancyId}/passkeys/ HTTP/1.1

JS/TS

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

const tenancyId = "myTenancyId";
const apiKey = "myApiKey";

await listPasskeys({}, { tenancyId, apiKey });

Authentication

Server-side REST API calls require authentication. Provide your tenancy-specific API Key via a Bearer authorization header:

HTTP

GET https://api.passlock.dev/v2/{tenancyId}/passkeys/ HTTP/1.1
Authorization: Bearer {apiKey}

JS/TS

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

await listPasskeys({}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

The passkey registration and authentication options and verification endpoints are browser-facing continuations of a prepared operation. They use the registrationToken, authenticationToken, or sessionToken issued earlier in the flow rather than a tenancy API key.

JSON

REST calls return JSON:

HTTP

GET https://api.passlock.dev/v2/{tenancyId}/passkeys/ HTTP/1.1
Authorization: Bearer {apiKey}
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

JS/TS

Not applicable, the server library handles JSON internally.

Endpoint summary

• GET /v2/{tenancyId}/principal/{code} exchanges a browser-issued code for an ExtendedPrincipal
• GET /v2/{tenancyId}/passkeys/ lists passkey summaries
• GET /v2/{tenancyId}/passkeys/{passkeyId} fetches a passkey
• PATCH /v2/{tenancyId}/passkeys/{passkeyId} updates a passkey username
• DELETE /v2/{tenancyId}/passkeys/{passkeyId} deletes a passkey
• PATCH /v2/{tenancyId}/users/{userId}/passkeys/ updates username metadata for a user’s passkeys
• DELETE /v2/{tenancyId}/users/{userId}/passkeys/ deletes a user’s passkeys
• POST /v2/{tenancyId}/challenges creates a mailbox challenge
• GET /v2/{tenancyId}/challenges/{challengeId} reads a pending mailbox challenge
• POST /v2/{tenancyId}/challenges/verify verifies a mailbox challenge
• DELETE /v2/{tenancyId}/challenges/{challengeId} deletes a mailbox challenge
• POST /v2/{tenancyId}/passkey/registration/prepare prepares a passkey registration
• POST /v2/{tenancyId}/passkey/registration/options creates WebAuthn registration options
• POST /v2/{tenancyId}/passkey/registration/verification verifies a registration response
• POST /v2/{tenancyId}/passkey/authentication/prepare prepares a passkey authentication
• POST /v2/{tenancyId}/passkey/authentication/options creates WebAuthn authentication options
• POST /v2/{tenancyId}/passkey/authentication/verification verifies an authentication response