List credentials

GET /api/auth/credential admin

Every public-key credential registered on the deployment — passkeys and security keys — paged by cursor.

Parameters

cursor string

Continue from a previous page. Query parameter.

limit number

Page size. Query parameter.

Returns

The page of credentials, and a cursor when there is more.

Request

curl https://example.com/api/auth/credential \
  -H "authorization: Bearer $TOKEN"

Response

{
  "credentials": [
    { "id": "AXcv…", "identity": "01J2788XY98FDTA410C8S716CD" }
  ],
  "cursor": null
}

Read a credential

GET /api/auth/credential/:id open

The stored public-key credential, by the id the authenticator returned when it was created.

Parameters

id string Required

The credential id. Path parameter.

Returns

The credential, or 404.

Request

curl https://example.com/api/auth/credential/AXcv1234

Response

{
  "id": "AXcv1234",
  "publicKey": "pQECAyYgASFYIH…",
  "counter": 3
}

Check whether a credential exists

HEAD /api/auth/credential/:id open

The same lookup with no body.

Parameters

id string Required

Path parameter.

Returns

200 when it exists, 404 when not.

Request

curl -I https://example.com/api/auth/credential/AXcv1234

Response

{}

Look up the identity behind a credential

GET /api/auth/credential/:id/identity open

Which account a passkey belongs to. This is what makes a usernameless sign-in possible: the authenticator hands back a credential id and nothing else, and this turns it into an identity.

Parameters

id string Required

The credential id. Path parameter.

Returns

{ identity }, or 404 when the credential is unknown.

Request

curl https://example.com/api/auth/credential/AXcv1234/identity

Response

{
  "identity": {
    "id": "01J2788XY98FDTA410C8S716CD",
    "kind": "member",
    "displayName": "Ada Lovelace"
  }
}

Check whether a credential has an owner

HEAD /api/auth/credential/:id/identity open

The same lookup with no body.

Parameters

id string Required

Path parameter.

Returns

200 when the credential resolves, 404 when not.

Request

curl -I https://example.com/api/auth/credential/AXcv1234/identity

Response

{}

Issue a challenge

GET /api/auth/credential/challenge open

A fresh challenge string for an authenticator to sign — an id and a random salt joined by a colon.

It answers text/plain, not JSON. Worth knowing before wiring a client that assumes every endpoint here returns an object.

Returns

The challenge, as plain text.

Request

curl https://example.com/api/auth/credential/challenge

Response

"01J2788XY98FDTA410C8S716CD:9f2c41ba7d0e4a1f8b3c5d6e7f809a1b"

Check the challenge endpoint

HEAD /api/auth/credential/challenge open

The same call with no body.

Returns

200.

Request

curl -I https://example.com/api/auth/credential/challenge

Response

{}

Verify a signed challenge

POST /api/auth/credential/challenge open

Not implemented. Answers 501 with the signed challenge echoed back. Assertion is verified through POST /api/auth/credential/pubkey/assert instead.

Parameters

body string

The signed challenge, as plain text.

Returns

501.

Request

curl -X POST https://example.com/api/auth/credential/challenge \
  -H "content-type: text/plain" \
  --data "01J2788XY98FDTA410C8S716CD:9f2c…"

Response

{
  "signedChallenge": "01J2788XY98FDTA410C8S716CD:9f2c…"
}

Begin registering a passkey

POST /api/auth/credential/pubkey/attest open

Returns the PublicKeyCredentialCreationOptions to hand to navigator.credentials.create() — relying party, user handle, and a one-time challenge the worker remembers until the attestation comes back.

The relying party id is derived from the request, so this works on a preview deployment without configuration. If a session is present the credential is attached to that identity; otherwise a fresh id is minted for the account being created.

Parameters

name string Required

The account name shown by the authenticator — usually the email or username.

displayName string Required

The human name shown alongside it.

Returns

Creation options, ready to pass to the WebAuthn API.

curl -X POST https://example.com/api/auth/credential/pubkey/attest \
  -H "content-type: application/json" \
  -d '{ "name": "ada@example.com", "displayName": "Ada Lovelace" }'

const options = await fetch('/api/auth/credential/pubkey/attest', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'ada@example.com', displayName: 'Ada Lovelace' })
}).then((response) => response.json())

const credential = await navigator.credentials.create({ publicKey: options })

Response

{
  "rp": { "name": "Moddable", "id": "example.com" },
  "user": {
    "id": "01J2788XY98FDTA410C8S716CD",
    "name": "ada@example.com",
    "displayName": "Ada Lovelace"
  },
  "challenge": "9f2c41ba7d0e4a1f8b3c5d6e7f809a1b",
  "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }]
}

Begin signing in with a passkey

POST /api/auth/credential/pubkey/assert open

Returns the PublicKeyCredentialRequestOptions to hand to navigator.credentials.get() — a one-time challenge, and the credentials allowed to answer it.

Naming an identifier narrows the allow-list to that account's credentials. Omitting it leaves the list open, which is what a "sign in with a passkey" button with no username field wants.

Parameters

kind enum

Which identifier the body carries, when narrowing to one account.

Possible enum values

email
phone
username
identity

email | phone | username | identity string

The identifier named by kind.

Returns

Request options, ready to pass to the WebAuthn API.

Request

curl -X POST https://example.com/api/auth/credential/pubkey/assert \
  -H "content-type: application/json" \
  -d '{ "kind": "email", "email": "ada@example.com" }'

Response

{
  "rpId": "example.com",
  "challenge": "9f2c41ba7d0e4a1f8b3c5d6e7f809a1b",
  "allowCredentials": [{ "type": "public-key", "id": "AXcv1234" }],
  "userVerification": "preferred"
}

The shape of a flow

Usernameless sign-in

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns