---
name: bijection-convex-passkey-auth
description: "Evaluate and integrate the Convex Passkey-auth component with Bijection."
---

# Convex Passkey-auth

Passwordless WebAuthn passkey authentication — self-minted JWTs, multi-device support, session management, and React hooks for Convex.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-passkey-auth
- Source: https://github.com/TimpiaAI/convex-passkey-auth
- npm: https://www.npmjs.com/package/convex-passkey-auth
- Directory: https://bijection.com/components/convex-passkey-auth

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-passkey-auth. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# convex-passkey-auth

## Instructions

This component provides complete WebAuthn passkey authentication for Convex apps, handling the full challenge/response flow with self-minted HMAC-SHA256 JWTs. It includes multi-device support, session management, and React hooks for registration and login. The component eliminates passwords entirely while providing secure session tokens compatible with Convex's auth system.

### Installation

```bash
npm install convex-passkey-auth
```

## Use cases

• **Replace traditional password auth** with WebAuthn passkeys for better security and user experience
• **Build multi-device authentication** where users can authenticate from phones, laptops, and hardware security keys
• **Implement passwordless onboarding** with passkey registration and automatic user creation
• **Add secure session management** with configurable expiry, refresh tokens, and logout capabilities
• **Deploy preview environments** without hardcoded origins since rpId is derived from the client

## How it works

The component provides a `PasskeyAuth` class that handles WebAuthn challenge generation and verification through methods like `generateRegistrationOptions` and `verifyAuthentication`. You create Convex mutations that wrap these methods, then use the provided React hooks (`usePasskeyRegister`, `usePasskeyLogin`, `usePasskeyAuth`) to handle the browser WebAuthn APIs.

Session tokens are HMAC-SHA256 signed JWTs that integrate directly with Convex's auth system. The `validateSession` method checks token validity and returns user data, while `getOrCreateUser` provides stable user identifiers from passkey credentials. The component stores passkeys, sessions, and challenges in Convex tables with automatic cleanup via cron jobs.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by convex-passkey-auth is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-passkey-auth)
- [GitHub repository](https://github.com/TimpiaAI/convex-passkey-auth)
- [Live demo](https://passkey-auth-demo-iota.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-passkey-auth)
- [Convex documentation](https://docs.convex.dev)