Skip to content
Passlock
Login Signup Docs

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
  • Prepare passkey update, deletion, and pruning operations
  • Authorize and complete passkey registration and authentication operations

Tenancy ID

Section titled “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.

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

Authentication

Section titled “Authentication”

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

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

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

JSON

Section titled “JSON”

REST calls return JSON:

HTTP Request
GET https://api.passlock.dev/v2/\{tenancyId\}/passkeys/ HTTP/1.1
Authorization: Bearer \{apiKey\}
Accept: application/json
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json

Endpoint summary

Section titled “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
POST /v2/{tenancyId}/passkeys/update
Updates username metadata and prepares browser update instructions
POST /v2/{tenancyId}/passkeys/update/exchange
Exchanges a prepared update token for browser instructions
POST /v2/{tenancyId}/passkeys/delete
Deletes passkeys and prepares browser removal instructions
POST /v2/{tenancyId}/passkeys/delete/exchange
Exchanges a prepared deletion token for browser instructions
POST /v2/{tenancyId}/passkeys/prune
Prepares accepted-credential pruning instructions for a user
POST /v2/{tenancyId}/passkeys/prune/exchange
Exchanges a prepared pruning token for browser instructions
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/authorize
Authorizes 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/authorize
Authorizes a passkey authentication
POST /v2/{tenancyId}/passkey/authentication/options
Creates WebAuthn authentication options
POST /v2/{tenancyId}/passkey/authentication/verification
Verifies an authentication response