> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# WebAuthn

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

## Overview

The `webauthn` client manages FIDO2/WebAuthn passkey credentials for your end-users. Register passkeys, verify attestation responses, list credentials, and delete them.

Access the webauthn client via `client.webauthn`.

## Register Options

Generate WebAuthn registration options for a principal. Returns a `PublicKeyCredentialCreationOptions`-compatible dict to pass to the browser's `navigator.credentials.create()`.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    options = client.webauthn.register_options("user_abc123")

    print(f"Challenge: {options.challenge}")
    print(f"RP: {options.rp}")
    print(f"User: {options.user}")
    print(f"Timeout: {options.timeout}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `principal_id` | `str` | Yes | The ID of the principal (end-user) to register a passkey for. |

### WebAuthnRegisterOptions

| Field | Type | Description |
| - | - | - |
| `challenge` | `str` | Base64url-encoded challenge for the registration ceremony. |
| `rp` | `dict` | Relying party information (`name`, `id`). |
| `user` | `dict` | User entity (`id`, `name`, `display_name`). |
| `pub_key_cred_params` | `list[dict]` | Supported public key algorithms (e.g., ES256, RS256). |
| `timeout` | `int` | Timeout in milliseconds for the registration ceremony. |
| `attestation` | `str` | Attestation conveyance preference. |
| `exclude_credentials` | `list[dict]` | Existing credential descriptors to prevent re-registration. |

## Register Verify

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

```python theme={null}
from grantex import Grantex, WebAuthnRegisterVerifyParams

with Grantex(api_key="gx_live_...") as client:
    credential = client.webauthn.register_verify(WebAuthnRegisterVerifyParams(
        principal_id="user_abc123",
        credential={
            "id": "base64url-credential-id",
            "rawId": "base64url-raw-id",
            "type": "public-key",
            "response": {
                "clientDataJSON": "base64url-encoded",
                "attestationObject": "base64url-encoded",
            },
        },
    ))

    print(f"Credential ID: {credential.credential_id}")
    print(f"Public key: {credential.public_key}")
    print(f"Sign count: {credential.sign_count}")
    print(f"Created at: {credential.created_at}")
```

### WebAuthnRegisterVerifyParams

| Parameter | Type | Required | Description |
| - | - | - | - |
| `principal_id` | `str` | Yes | The principal ID that this credential belongs to. |
| `credential` | `dict` | Yes | The WebAuthn attestation response from `navigator.credentials.create()`. |

### WebAuthnCredential

| Field | Type | Description |
| - | - | - |
| `credential_id` | `str` | Unique credential identifier. |
| `public_key` | `str` | Base64url-encoded public key. |
| `sign_count` | `int` | The signature counter value. |
| `created_at` | `str` | ISO 8601 timestamp when the credential was registered. |
| `aaguid` | `str` | The authenticator attestation GUID. |
| `last_used_at` | `str \| None` | ISO 8601 timestamp of last authentication, or `None`. |

## List Credentials

List all WebAuthn credentials registered for a principal.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    credentials = client.webauthn.list_credentials("user_abc123")

    for cred in credentials:
        print(f"{cred.credential_id} — created {cred.created_at}")
        print(f"  Last used: {cred.last_used_at or 'never'}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `principal_id` | `str` | Yes | The principal ID to list credentials for. |

### Response

Returns a `list[WebAuthnCredential]`. See above for field descriptions.

## Delete Credential

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

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    client.webauthn.delete_credential("cred_01HXYZ...")
    # Returns None — credential is deleted
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `credential_id` | `str` | Yes | The credential ID to delete. |

The method returns `None`. A `GrantexApiError` is raised if the credential does not exist.

## Example: Full Passkey Flow

```python theme={null}
from grantex import Grantex, WebAuthnRegisterVerifyParams

with Grantex(api_key="gx_live_...") as client:
    # 1. Generate registration options (send to browser)
    options = client.webauthn.register_options("user_abc123")
    # → Send options to the client for navigator.credentials.create()

    # 2. Verify the attestation response (received from browser)
    credential = client.webauthn.register_verify(WebAuthnRegisterVerifyParams(
        principal_id="user_abc123",
        credential=attestation_response_from_browser,
    ))
    print(f"Registered passkey: {credential.credential_id}")

    # 3. List all passkeys for the user
    all_credentials = client.webauthn.list_credentials("user_abc123")
    print(f"User has {len(all_credentials)} passkey(s)")

    # 4. Delete a passkey when the user requests removal
    client.webauthn.delete_credential(credential.credential_id)
```

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.