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

# Environment variables

> All environment variables required to run Digcrate

Copy `.env.local.example` to `.env.local` and fill in the values below.

```bash theme={null}
cp .env.local.example .env.local
```

***

## Clerk (authentication)

Clerk handles user sign-in, sign-up, and session management.

```env theme={null}
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_WEBHOOK_SECRET=whsec_xxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
```

| Variable                            | Description                                                       |
| ----------------------------------- | ----------------------------------------------------------------- |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Client-side Clerk key. Found in your Clerk application dashboard. |
| `CLERK_SECRET_KEY`                  | Server-side Clerk key. Keep this secret.                          |
| `CLERK_WEBHOOK_SECRET`              | Webhook signing secret for syncing user records to Convex.        |
| `NEXT_PUBLIC_CLERK_SIGN_IN_URL`     | Path for the sign-in page. Use `/sign-in`.                        |
| `NEXT_PUBLIC_CLERK_SIGN_UP_URL`     | Path for the sign-up page. Use `/sign-up`.                        |

***

## Convex (database)

Convex stores all application state — sessions, messages, playlists, usage events, subscriptions, influence graphs, and more.

```env theme={null}
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
```

| Variable                 | Description                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `NEXT_PUBLIC_CONVEX_URL` | Your Convex deployment URL. Set automatically by `npx convex dev` and `npx convex deploy`. |

<Note>
  `CONVEX_DEPLOYMENT` (e.g. `dev:your-project-name`) is written to `.env.local` automatically by the Convex CLI during `npx convex dev`. You do not need to set it manually.
</Note>

***

## Encryption

Used to encrypt API keys stored in the database.

```env theme={null}
ENCRYPTION_KEY=
```

| Variable         | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `ENCRYPTION_KEY` | A 64-character hexadecimal string used to encrypt user API keys at rest. |

Generate a secure value with:

```bash theme={null}
openssl rand -hex 32
```

<Warning>
  Changing `ENCRYPTION_KEY` after users have saved API keys will make those keys unreadable. Store this value securely and do not rotate it without a migration plan.
</Warning>

***

## Platform AI key

The Anthropic API key Digcrate uses to serve free and Pro users who have not configured their own key (BYOK).

```env theme={null}
PLATFORM_ANTHROPIC_KEY=sk-ant-xxx
```

| Variable                 | Description                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `PLATFORM_ANTHROPIC_KEY` | Your platform-level Anthropic API key. Costs are billed to this key for all non-BYOK queries. |

<Warning>
  This variable is required for the platform to serve free-tier users. Without it, only BYOK users can run queries. All other users will receive an error when attempting to start a research session.
</Warning>

***

## Admin

```env theme={null}
ADMIN_EMAILS=admin@example.com
```

| Variable       | Description                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ADMIN_EMAILS` | Comma-separated list of email addresses. Users with these emails bypass all rate limits, usage quotas, and feature gates. |

***

## Embedded API keys

These keys are embedded in the server and used by the agent's MCP tools. They are optional — the agent will skip tools that lack a key — but enabling them unlocks more data sources.

```env theme={null}
EMBEDDED_LASTFM_KEY=
EMBEDDED_DISCOGS_KEY=
EMBEDDED_DISCOGS_SECRET=
EMBEDDED_TICKETMASTER_KEY=
```

| Variable                    | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `EMBEDDED_LASTFM_KEY`       | [Last.fm API key](https://www.last.fm/api) for similar artists, tags, and listening stats. |
| `EMBEDDED_DISCOGS_KEY`      | [Discogs app key](https://www.discogs.com/settings/developers) for release and label data. |
| `EMBEDDED_DISCOGS_SECRET`   | Discogs app secret, paired with `EMBEDDED_DISCOGS_KEY`.                                    |
| `EMBEDDED_TICKETMASTER_KEY` | [Ticketmaster API key](https://developer.ticketmaster.com) for concert listings.           |

***

## Stripe (billing)

Required to enable subscription plans (Free, Pro, Team) and the billing portal.

```env theme={null}
STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_PRO_MONTHLY_PRICE_ID=price_xxx
STRIPE_PRO_ANNUAL_PRICE_ID=price_xxx
STRIPE_TEAM_MONTHLY_PRICE_ID=price_xxx
```

| Variable                             | Description                                        |
| ------------------------------------ | -------------------------------------------------- |
| `STRIPE_SECRET_KEY`                  | Server-side Stripe secret key.                     |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Client-side Stripe publishable key.                |
| `STRIPE_WEBHOOK_SECRET`              | Webhook signing secret for `/api/webhooks/stripe`. |
| `STRIPE_PRO_MONTHLY_PRICE_ID`        | Stripe Price ID for the Pro monthly plan.          |
| `STRIPE_PRO_ANNUAL_PRICE_ID`         | Stripe Price ID for the Pro annual plan.           |
| `STRIPE_TEAM_MONTHLY_PRICE_ID`       | Stripe Price ID for the Team monthly plan.         |

<Note>
  Stripe is optional. If omitted, all users will be treated as free-tier. Subscription upgrades and the billing portal will not be available.
</Note>

***

## Auth0 Token Vault (connected services)

Required to enable Spotify, Slack, and Google Docs integrations. Auth0 Token Vault securely manages OAuth tokens on behalf of users — Digcrate never stores raw credentials.

```env theme={null}
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your-auth0-client-id
AUTH0_CLIENT_SECRET=your-auth0-client-secret
AUTH0_TOKEN_VAULT_AUDIENCE=https://your-api-audience
AUTH0_CALLBACK_URL=http://localhost:3000/api/auth0/callback
```

| Variable                     | Description                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `AUTH0_DOMAIN`               | Your Auth0 tenant domain (e.g. `your-tenant.us.auth0.com`).                                                         |
| `AUTH0_CLIENT_ID`            | Auth0 application client ID.                                                                                        |
| `AUTH0_CLIENT_SECRET`        | Auth0 application client secret.                                                                                    |
| `AUTH0_TOKEN_VAULT_AUDIENCE` | The API audience configured in Auth0 for Token Vault.                                                               |
| `AUTH0_CALLBACK_URL`         | OAuth callback URL. Set to your production domain in production (e.g. `https://yourdomain.com/api/auth0/callback`). |

<Note>
  Auth0 Token Vault is optional. Without it, connected services (Spotify, Slack, Google Docs) will not be available to users.
</Note>

***

## Beta domains

```env theme={null}
BETA_DOMAINS=radiomilwaukee.org
```

| Variable       | Description                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETA_DOMAINS` | Comma-separated list of email domains. Users signing up with these email domains automatically receive Pro access at no charge. Useful for beta testers, partner organizations, or radio stations. |

<Note>
  This variable is optional.
</Note>

***

## Optional: Canny feedback widget

```env theme={null}
NEXT_PUBLIC_CANNY_APP_ID=your-canny-app-id
NEXT_PUBLIC_CANNY_URL=https://your-company.canny.io
```

| Variable                   | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| `NEXT_PUBLIC_CANNY_APP_ID` | [Canny](https://canny.io) app ID for the in-app feedback widget. |
| `NEXT_PUBLIC_CANNY_URL`    | Your Canny board URL.                                            |

<Note>
  Canny is optional. If omitted, the feedback widget will not appear.
</Note>