Nullgap.dev Docs

API reference

Passkeys

The signed-in person’s passkeys.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
List passkeysGET /api/me/passkeysconsole session
Add a passkeyPOST /api/me/passkeysconsole session
Get passkey creation optionsPOST /api/me/passkeys/optionsconsole session
Rename a passkeyPATCH /api/me/passkeys/{id}console session
Remove a passkeyDELETE /api/me/passkeys/{id}console session

#List passkeys

GET /api/me/passkeys

Lists the passkeys on the signed-in person's account, oldest first. The answer is a plain array, not a paged list.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

Every passkey on the account, oldest first.

An array of PasskeyInfo.

[
  {
    "id": "9c1f4e7a2b8d03561fae47c2",
    "name": "Work laptop",
    "createdAt": "2026-10-02T08:20:00.000Z",
    "lastUsedAt": "2026-11-16T09:12:00.000Z",
    "synced": true
  }
]

#Add a passkey

POST /api/me/passkeys

Second step of adding a passkey: send the credential the browser created from the options. If this is the account's first second factor, the current session becomes a verified one with a new cookie and every other session of the person is signed out.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Request body (application/json)

FieldTypeRequiredDescription
namestringnoA label for the passkey. Trimmed, and cut to 60 characters. "Passkey" when left out or blank.
credentialobjectyesThe PublicKeyCredential that navigator.credentials.create returned, with every binary field as base64url.
credential.idstringnoThe credential id, base64url.
credential.rawIdstringnoThe credential id again, base64url. When sent it must equal the id inside the attestation.
credential.typestringnoAlways public-key.
credential.responseobjectyesThe response of the credential.
credential.response.clientDataJSONstringyesThe browser's client data, base64url. It must carry the challenge from the options call.
credential.response.attestationObjectstringyesThe attestation object from the device, base64url.
credential.response.transportsarray of stringnoWhat getTransports() returned. Unknown values are dropped; at most six are kept.

Answer (200, application/json)

A PasskeyInfo object.

{
  "id": "9c1f4e7a2b8d03561fae47c2",
  "name": "Work laptop",
  "createdAt": "2026-10-02T08:20:00.000Z",
  "lastUsedAt": "2026-11-16T09:12:00.000Z",
  "synced": true
}

Errors specific to this call

StatusCodeWhen
400passkey_invalidThe credential is missing or could not be verified: for example the challenge is unknown, already used, expired or was issued to another account. The reason is not disclosed.
409passkey_existsThat passkey is already registered, on this account or another.

#Get passkey creation options

POST /api/me/passkeys/options

First step of adding a passkey. Returns the WebAuthn options to pass to navigator.credentials.create in the browser. The challenge inside can be used once and expires after 5 minutes. Takes no request body.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

A PasskeyCreationOptions object.

{
  "challenge": "q83vEjRWeJCrze8SNFZ4kKvN7xI0VniQq83vEjRWeJA",
  "rp": {
    "id": "app.nullgap.dev",
    "name": "Nullgap"
  },
  "user": {
    "id": "dXNyXzRiMWQ5YzdlMmEwZg",
    "name": "dana@acme.example",
    "displayName": "Dana Okafor"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "timeout": 120000,
  "attestation": "none",
  "authenticatorSelection": {
    "residentKey": "required",
    "requireResidentKey": true,
    "userVerification": "required"
  },
  "excludeCredentials": [
    {
      "type": "public-key",
      "id": "Zm9vYmFyYmF6cXV4Y3JlZGVudGlhbGlk",
      "transports": [
        "internal"
      ]
    }
  ]
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and this session has not passed a second-factor check in the last 15 minutes. Confirm with a code or a passkey, then call again.
400passkey_limitThe account already has 20 passkeys. Remove one first.

#Rename a passkey

PATCH /api/me/passkeys/{id}

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Path parameters

NameTypeRequiredDescription
idstringyesThe passkey id from the list (24 hexadecimal characters).

Request body (application/json)

FieldTypeRequiredDescription
namestringyesThe new label. Trimmed, and cut to 60 characters.

Answer (200, application/json)

A PasskeyInfo object.

{
  "id": "9c1f4e7a2b8d03561fae47c2",
  "name": "Work laptop",
  "createdAt": "2026-10-02T08:20:00.000Z",
  "lastUsedAt": "2026-11-16T09:12:00.000Z",
  "synced": true
}

Errors specific to this call

StatusCodeWhen
404not_foundThe signed-in person has no passkey with that id.
400bad_requestname is missing, not text, or blank.

#Remove a passkey

DELETE /api/me/passkeys/{id}

Removes a passkey from the signed-in person's account. It can no longer be used to sign in or to confirm actions.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Path parameters

NameTypeRequiredDescription
idstringyesThe passkey id from the list (24 hexadecimal characters).

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundThe signed-in person has no passkey with that id.
403step_up_requiredYour account has a second factor and this session has not passed a second-factor check in the last 15 minutes. Confirm with a code or a passkey, then call again.

#Objects

The objects the operations above take and return.

#PasskeyInfo

A passkey on the signed-in person's account. The key material is never returned.

FieldTypeAlways presentDescription
idstringyesThe id to use for renaming and removing the passkey. 24 hexadecimal characters.
namestringyesThe label the person gave it. At most 60 characters. "Passkey" when none was given.
createdAtstringyesWhen the passkey was added.
lastUsedAtstring or nullyesWhen it was last used to sign in or to confirm an action. Null if never.
syncedbooleanyesTrue when the device reports that the passkey is backed up and synced by its platform or a password manager.

#PasskeyRegistration

FieldTypeAlways presentDescription
namestringnoA label for the passkey. Trimmed, and cut to 60 characters. "Passkey" when left out or blank.
credentialobjectyesThe PublicKeyCredential that navigator.credentials.create returned, with every binary field as base64url.
credential.idstringnoThe credential id, base64url.
credential.rawIdstringnoThe credential id again, base64url. When sent it must equal the id inside the attestation.
credential.typestringnoAlways public-key.
credential.responseobjectyesThe response of the credential.
credential.response.clientDataJSONstringyesThe browser's client data, base64url. It must carry the challenge from the options call.
credential.response.attestationObjectstringyesThe attestation object from the device, base64url.
credential.response.transportsarray of stringnoWhat getTransports() returned. Unknown values are dropped; at most six are kept.

#PasskeyCreationOptions

WebAuthn creation options in JSON form: every binary value is base64url. Convert them to buffers and pass them to navigator.credentials.create.

FieldTypeAlways presentDescription
challengestringyesA single-use value the device signs, base64url. Valid for 5 minutes.
rpobjectyesThe site the passkey belongs to.
rp.idstringyesThe host name of the Nullgap console the passkey is bound to.
rp.namestringyesThe name the device shows.
userobjectyesThe account the passkey will sign in.
user.idstringyesAn opaque handle for the account, base64url. It carries no personal data.
user.namestringyesThe account's email address.
user.displayNamestringyesThe person's name, or the email address when no name is set.
pubKeyCredParamsarray of objectyesThe signature algorithms accepted, in order of preference.
pubKeyCredParams[].typestringyesAlways public-key.
pubKeyCredParams[].algintegeryesA COSE algorithm number: -7 (ES256), -8 (EdDSA) or -257 (RS256). One of: -7, -8, -257.
timeoutintegeryesHow long the browser should wait for the person, in milliseconds. Always 120000.
attestationstringyesAlways none: no statement about the device's make is asked for.
authenticatorSelectionobjectyesWhat kind of passkey is accepted.
authenticatorSelection.residentKeystringyesAlways required: the passkey must be discoverable, so it can sign in without a user name.
authenticatorSelection.requireResidentKeybooleanyesAlways true.
authenticatorSelection.userVerificationstringyesAlways required: the device must check the person (biometric or PIN).
excludeCredentialsarray of PasskeyCredentialRefyesThe passkeys already on the account, so the same device is not registered twice.

#PasskeyCredentialRef

A passkey that already exists, as WebAuthn refers to it.

FieldTypeAlways presentDescription
typestringyesAlways public-key.
idstringyesThe credential id, base64url.
transportsarray of stringnoHow the device can be reached. Left out when the browser did not say.

Nullgap documentation