Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Draft] Keyless docs #1699

Draft
wants to merge 17 commits into
base: main
Choose a base branch
from
42 changes: 42 additions & 0 deletions docs/keyless.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Keyless Mode
description: Develop locally without requiring a Clerk account.
---

**Keyless Mode** allows you to try out Clerk in your local development environment without having to sign up for a Clerk account.

## How does it work?

If Clerk's SDK doesn't detect valid [Clerk keys](TODO) in your environment, it will automatically fetch a set of keys for you. These keys are associated with a Clerk development instance that has a default configuration. When running locally in Keyless Mode, you'll see a UI toast indicating that you're running in this special mode with a link to claim your instance by signing up for a Clerk account, or signing in if you already have one.

Keys are written to a file in a `.clerk` directory in your project. The Clerk SDK will try to add this directory to your `.gitignore` file to prevent keys from being committed to your repository.

### Default configuration

Clerk development instances have the following default configuration:

- **Authentication**: Email and password, Sign-in with Google, Sign-in with GitHub
- **Verification**: Email verification is required
- **Password reset**: Password reset is enabled
- **MFA**: MFA is disabled
- **Appearance**: Default appearance

When using Clerk in Keyless Mode, you're not able to make configuration changes to your instance. To make changes, [claim your instance](#claiming-keys).

## Keyless Mode support

Keyless mode works with Clerk's SDKs for [Next.js](/docs/quickstarts/nextjs). If you're using a different framework or SDk, you'll need to manually configure Clerk keys in your environment. Visit the [Clerk Dashboard](https://dashboard.clerk.com/sign-up) to create an account, create an instance, and get your keys.
mwickett marked this conversation as resolved.
Show resolved Hide resolved

## Claiming keys

When you're ready to make configuration changes to your instance, you can claim the automatically generated keys. To do this, click the "Claim keys" button in the Clerk toolbar on your local application. You'll then be prompted to sign up for a Clerk account, or sign in if you already have one. After authenticating, give your application a name and the keys will be associated with your account.

![Claim keys modal](/docs/images/keyless/claim-keys.png)

You'll need to copy and paste the keys into your `.env` file to persist them in your project. This will disable Keyless Mode. If you don't add keys to your environment, you'll see a warning to let you know the instance has been claimed, but keys haven't been set.

![Claimed instance warning](/docs/images/keyless/setting-env-keys.png)

## Feedback

If you have any feedback or questions about Keyless Mode, please reach out to [Clerk Support](https://clerk.com/contact/support).
Binary file added public/images/keyless/claim-keys.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/images/keyless/setting-env-keys.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading