---
title: Installation
description: Install convex-auth, generate keys, and set your environment variables.
sidebar:
  order: 1
---

This guide installs the packages and sets the minimum environment variables. For the full end-to-end wiring, follow [`Quickstart`](/convex-auth/quickstart).

## What you need

- A Convex project. If you do not have one, run `pnpm dlx convex@latest`.
- pnpm and Node `>=22.0.0`.
- An email service for production (Resend, Postmark, SES, etc.). For local development you can log email drafts.

## Steps

1. **Install packages**

    ```bash
    pnpm add @vortex-api/convex-auth @vortex-api/convex-auth/react convex
    ```

2. **Generate signing keys**

    `convex-auth` signs session JWTs with RS256. Run this once:

    ```bash
    node --input-type=module -e '
    import { randomUUID } from "node:crypto";
    import { generateKeyPair, exportJWK } from "jose";
    const { publicKey, privateKey } = await generateKeyPair("RS256", { extractable: true });
    const pub = await exportJWK(publicKey);
    const priv = await exportJWK(privateKey);
    const kid = randomUUID();
    pub.kid = kid;
    priv.kid = kid;
    console.log("JWT_PRIVATE_KEY=" + JSON.stringify(priv));
    console.log("JWKS=" + JSON.stringify({ keys: [pub] }));
    '
    ```

3. **Set environment variables**

    ```bash
    pnpm dlx convex env set JWT_PRIVATE_KEY '<private-key-json>'
    pnpm dlx convex env set JWKS '<jwks-json>'
    pnpm dlx convex env set CONVEX_SITE_URL 'https://your-site.convex.site'
    pnpm dlx convex env set EMAIL_FROM_ADDRESS 'auth@yourdomain.com'
    ```

    > **Warning**
    >
    > Keep `JWT_PRIVATE_KEY` secret. Never commit it. Use `convex env set` for both local and production deployments.

4. **Continue to Quickstart**

    The next page wires the component, `convex/auth.ts`, and the React client.

## Supported versions

`convex-auth` is tested against the following ranges:

| Package / subpath                      | Version | Convex     | React      | React Native / Expo | Node       | pnpm      |
| -------------------------------------- | ------- | ---------- | ---------- | ------------------- | ---------- | --------- |
| `@vortex-api/convex-auth`              | `3.x`   | `>=1.45.0` | `>=19.0.0` | —                   | `>=22.0.0` | `10.25.0` |
| `@vortex-api/convex-auth/react`        | `3.x`   | `>=1.45.0` | `>=19.0.0` | —                   | `>=22.0.0` | `10.25.0` |
| `@vortex-api/convex-auth/react-native` | `3.x`   | `>=1.45.0` | `>=19.0.0` | `expo-*` (optional) | `>=22.0.0` | `10.25.0` |

- **Convex** — `>=1.45.0` covers the modern backend system and generated component API.
- **React** — React 19 is the primary target; the client side does not depend on a specific React 18 release.
- **Node** — CI runs on Node 22 (floor) and Node 24 (newest LTS). Node 20 is EOL; older versions are unsupported.
- **pnpm** — the workspace uses pnpm only.

## Updating Convex

If you want to widen the `convex` peer range:

1. Update the range in `packages/auth/package.json`.
2. Run `pnpm run typecheck`, `pnpm run build`, and `pnpm test` from the repo root.
3. Do not widen a peer range without running the full test suite.

## Optional: set OAuth credentials

If you want Google, GitHub, or Discord sign-in, also set these and register the callback URL `https://<CONVEX_SITE_URL>/api/auth/callback/<provider>`:

```bash
pnpm dlx convex env set GITHUB_CLIENT_ID '...'
pnpm dlx convex env set GITHUB_CLIENT_SECRET '...'
pnpm dlx convex env set GOOGLE_CLIENT_ID '...'
pnpm dlx convex env set GOOGLE_CLIENT_SECRET '...'
pnpm dlx convex env set DISCORD_CLIENT_ID '...'
pnpm dlx convex env set DISCORD_CLIENT_SECRET '...'
```