WebAuthn

Register and manage FIDO2/WebAuthn passkey credentials for end-users.

Overview

The webauthn sub-client manages FIDO2/WebAuthn passkey credentials for your end-users. You can generate registration options, verify registration responses, list credentials, and delete them.

// Register a passkey, list credentials, delete one
const options = await grantex.webauthn.registerOptions({ principalId: 'user_abc123' });
const credential = await grantex.webauthn.registerVerify({ principalId: 'user_abc123', credential: attestation });
const credentials = await grantex.webauthn.listCredentials('user_abc123');
await grantex.webauthn.deleteCredential('cred_01HXYZ...');

---

webauthn.registerOptions()

Generate WebAuthn registration options for a principal. Returns a PublicKeyCredentialCreationOptions-compatible object that you pass to navigator.credentials.create() in the browser.

const options = await grantex.webauthn.registerOptions({
  principalId: 'user_abc123',
});

console.log(options.challenge);       // base64url-encoded challenge
console.log(options.rp);              // { name: 'Grantex', id: 'grantex.dev' }
console.log(options.user);            // { id, name, displayName }
console.log(options.pubKeyCredParams); // [{ type: 'public-key', alg: -7 }, ...]
console.log(options.timeout);         // 60000
console.log(options.attestation);     // 'none'

Parameters

principalId · string · required

The ID of the principal (end-user) to register a passkey for.

Response: WebAuthnRegisterOptions

challenge · string

Base64url-encoded challenge for the registration ceremony.

rp · object

Relying party information (name, id).

user · object

User entity (id, name, displayName) for the credential.

pubKeyCredParams · object[]

Supported public key algorithms (e.g., ES256, RS256).

timeout · number

Timeout in milliseconds for the registration ceremony.

attestation · string

Attestation conveyance preference ('none', 'indirect', 'direct').

excludeCredentials · object[]

List of existing credential descriptors to prevent re-registration.

---

webauthn.registerVerify()

Verify a WebAuthn registration response from the browser. On success, the credential is stored and associated with the principal.

const credential = await grantex.webauthn.registerVerify({
  principalId: 'user_abc123',
  credential: {
    id: 'base64url-credential-id',
    rawId: 'base64url-raw-id',
    type: 'public-key',
    response: {
      clientDataJSON: 'base64url-encoded',
      attestationObject: 'base64url-encoded',
    },
  },
});

console.log(credential.credentialId); // 'cred_01HXYZ...'
console.log(credential.publicKey);     // 'base64url-encoded-public-key'
console.log(credential.signCount);     // 0
console.log(credential.createdAt);     // '2026-03-08T10:00:00Z'

Parameters

principalId · string · required

The principal ID that this credential belongs to.

credential · object · required

The WebAuthn attestation response from navigator.credentials.create(). Must include id, rawId, type, and response (with clientDataJSON and attestationObject).

Response: WebAuthnCredential

credentialId · string

Unique credential identifier.

publicKey · string

Base64url-encoded public key.

signCount · number

The signature counter (starts at 0).

createdAt · string

ISO 8601 timestamp when the credential was registered.

aaguid · string

The authenticator attestation GUID, identifying the authenticator model.

---

webauthn.listCredentials()

List all WebAuthn credentials registered for a principal.

const credentials = await grantex.webauthn.listCredentials('user_abc123');

for (const cred of credentials) {
  console.log(cred.credentialId); // 'cred_01HXYZ...'
  console.log(cred.createdAt);    // '2026-03-08T10:00:00Z'
  console.log(cred.lastUsedAt);   // '2026-03-08T14:30:00Z' or null
}

Parameters

principalId · string · required

The principal ID to list credentials for.

Response: WebAuthnCredential[]

Returns an array of WebAuthnCredential objects.

credentialId · string

Unique credential identifier.

publicKey · string

Base64url-encoded public key.

signCount · number

Current signature counter value.

createdAt · string

ISO 8601 timestamp when the credential was registered.

lastUsedAt · string | null

ISO 8601 timestamp of the last successful authentication, or null if never used.

---

webauthn.deleteCredential()

Delete a WebAuthn credential by its ID. The credential is immediately invalidated.

await grantex.webauthn.deleteCredential('cred_01HXYZ...');
// Returns void — credential is deleted

Parameters

credentialId · string · required

The credential ID to delete.

Response

Returns void. The credential is immediately removed and can no longer be used for authentication.

---

Full example

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// 1. Generate registration options (send to browser)
const options = await grantex.webauthn.registerOptions({
  principalId: 'user_abc123',
});
// → Send options to the client for navigator.credentials.create()

// 2. Verify the attestation response (received from browser)
const credential = await grantex.webauthn.registerVerify({
  principalId: 'user_abc123',
  credential: attestationResponseFromBrowser,
});
console.log(`Registered passkey: ${credential.credentialId}`);

// 3. List all passkeys for the user
const allCredentials = await grantex.webauthn.listCredentials('user_abc123');
console.log(`User has ${allCredentials.length} passkey(s)`);

// 4. Delete a passkey when the user requests removal
await grantex.webauthn.deleteCredential(credential.credentialId);