Skip to content

API reference: passkeys

Passkeys on the signed-in account: enrolling one, listing and forgetting enrolled devices, and declining the offer to enrol. Each passkey holds its own wrap of the master key, which only its authenticator’s PRF output opens.

GET /v1/passkeys

The account's enrolled devices, newest first. Needs a session.

Responses
Status Description Body
200

Enrolled devices.

PasskeyList application/json
401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/passkeys

Finishes enrolment, storing the credential and the key it unwraps. Needs a session.

Request body, application/json: Enrolment

Responses
Status Description Body
201

Device enrolled.

PasskeySummary application/json
400

Unusable label or wrapped key

Problem application/problem+json
401

Challenge expired or not signed in

Problem application/problem+json
409

Already enrolled

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

GET /v1/passkeys/{id}

Returns one enrolled device. Needs a session.

Parameters
Name In Type Description
id (required) path string

The credential id, url-safe base64.

Responses
Status Description Body
200

The enrolled device.

PasskeySummary application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
404

No such device

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

DELETE /v1/passkeys/{id}

Forgets one of the account's devices. Needs a session.

Parameters
Name In Type Description
id (required) path string

The credential id, url-safe base64.

Responses
Status Description Body
204

Device forgotten

400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
404

No such device

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/passkeys:beginEnrolment

Starts enrolment for the signed-in account, once its password is re-verified. Needs a session.

A passkey outlives a password change, so a session alone never adds one: the account’s current auth key is re-verified first, as a password change does.

Request body, application/json: EnrolmentStart

Responses
Status Description Body
200

Enrolment challenge.

EnrolChallenge application/json
400

The request is malformed

Problem application/problem+json
401

Credential rejected

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

Too many ceremonies under way

Problem application/problem+json

POST /v1/passkeys:declineOffer

Declines the offer to enrol, so it is never made again. Needs a session.

Responses
Status Description Body
204

Offer withdrawn

401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json