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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List passkeys | GET /api/me/passkeys | console session |
| Add a passkey | POST /api/me/passkeys | console session |
| Get passkey creation options | POST /api/me/passkeys/options | console session |
| Rename a passkey | PATCH /api/me/passkeys/{id} | console session |
| Remove a passkey | DELETE /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)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | A label for the passkey. Trimmed, and cut to 60 characters. "Passkey" when left out or blank. |
credential | object | yes | The PublicKeyCredential that navigator.credentials.create returned, with every binary field as base64url. |
credential.id | string | no | The credential id, base64url. |
credential.rawId | string | no | The credential id again, base64url. When sent it must equal the id inside the attestation. |
credential.type | string | no | Always public-key. |
credential.response | object | yes | The response of the credential. |
credential.response.clientDataJSON | string | yes | The browser's client data, base64url. It must carry the challenge from the options call. |
credential.response.attestationObject | string | yes | The attestation object from the device, base64url. |
credential.response.transports | array of string | no | What 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
| Status | Code | When |
|---|---|---|
| 400 | passkey_invalid | The 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. |
| 409 | passkey_exists | That 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 400 | passkey_limit | The 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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The passkey id from the list (24 hexadecimal characters). |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | The signed-in person has no passkey with that id. |
| 400 | bad_request | name 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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The passkey id from the list (24 hexadecimal characters). |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The signed-in person has no passkey with that id. |
| 403 | step_up_required | Your 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id to use for renaming and removing the passkey. 24 hexadecimal characters. |
name | string | yes | The label the person gave it. At most 60 characters. "Passkey" when none was given. |
createdAt | string | yes | When the passkey was added. |
lastUsedAt | string or null | yes | When it was last used to sign in or to confirm an action. Null if never. |
synced | boolean | yes | True when the device reports that the passkey is backed up and synced by its platform or a password manager. |
#PasskeyRegistration
| Field | Type | Always present | Description |
|---|---|---|---|
name | string | no | A label for the passkey. Trimmed, and cut to 60 characters. "Passkey" when left out or blank. |
credential | object | yes | The PublicKeyCredential that navigator.credentials.create returned, with every binary field as base64url. |
credential.id | string | no | The credential id, base64url. |
credential.rawId | string | no | The credential id again, base64url. When sent it must equal the id inside the attestation. |
credential.type | string | no | Always public-key. |
credential.response | object | yes | The response of the credential. |
credential.response.clientDataJSON | string | yes | The browser's client data, base64url. It must carry the challenge from the options call. |
credential.response.attestationObject | string | yes | The attestation object from the device, base64url. |
credential.response.transports | array of string | no | What 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.
| Field | Type | Always present | Description |
|---|---|---|---|
challenge | string | yes | A single-use value the device signs, base64url. Valid for 5 minutes. |
rp | object | yes | The site the passkey belongs to. |
rp.id | string | yes | The host name of the Nullgap console the passkey is bound to. |
rp.name | string | yes | The name the device shows. |
user | object | yes | The account the passkey will sign in. |
user.id | string | yes | An opaque handle for the account, base64url. It carries no personal data. |
user.name | string | yes | The account's email address. |
user.displayName | string | yes | The person's name, or the email address when no name is set. |
pubKeyCredParams | array of object | yes | The signature algorithms accepted, in order of preference. |
pubKeyCredParams[].type | string | yes | Always public-key. |
pubKeyCredParams[].alg | integer | yes | A COSE algorithm number: -7 (ES256), -8 (EdDSA) or -257 (RS256). One of: -7, -8, -257. |
timeout | integer | yes | How long the browser should wait for the person, in milliseconds. Always 120000. |
attestation | string | yes | Always none: no statement about the device's make is asked for. |
authenticatorSelection | object | yes | What kind of passkey is accepted. |
authenticatorSelection.residentKey | string | yes | Always required: the passkey must be discoverable, so it can sign in without a user name. |
authenticatorSelection.requireResidentKey | boolean | yes | Always true. |
authenticatorSelection.userVerification | string | yes | Always required: the device must check the person (biometric or PIN). |
excludeCredentials | array of PasskeyCredentialRef | yes | The passkeys already on the account, so the same device is not registered twice. |
#PasskeyCredentialRef
A passkey that already exists, as WebAuthn refers to it.
| Field | Type | Always present | Description |
|---|---|---|---|
type | string | yes | Always public-key. |
id | string | yes | The credential id, base64url. |
transports | array of string | no | How the device can be reached. Left out when the browser did not say. |
Nullgap documentation