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

feat: Machine Token Docs #1725

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/_partials/clerk-middleware-options.mdx
Original file line number Diff line number Diff line change
@@ -39,7 +39,7 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
- `jwtKey`
- `string`

Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt).

---

2 changes: 1 addition & 1 deletion docs/_partials/clerk-options.mdx
Original file line number Diff line number Diff line change
@@ -9,7 +9,7 @@
- `jwtKey?`
- `string`

The PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
The PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt).

---

2 changes: 1 addition & 1 deletion docs/_partials/root-auth-loader.mdx
Original file line number Diff line number Diff line change
@@ -32,7 +32,7 @@ The `rootAuthLoader()` function accepts an optional object. The following option
- `jwtKey`
- `string`

Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) instead.** For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt).

---

2 changes: 1 addition & 1 deletion docs/_partials/token-size-callout.mdx
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
> [!CAUTION]
> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
> It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend.
> [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).
> [Learn more](/docs/session-requests/session-tokens#size-limitations).
4 changes: 2 additions & 2 deletions docs/authentication/configuration/session-options.mdx
Original file line number Diff line number Diff line change
@@ -75,6 +75,6 @@ There are two main ways to add the multi-session feature to your application:

## Customize session token

Session tokens are JWTs that contain a set of [default claims](/docs/backend-requests/resources/session-tokens) required by Clerk. You can customize these tokens by providing additional claims of your own.
Session tokens are JWTs that contain a set of [default claims](/docs/session-requests/session-tokens) required by Clerk. You can customize these tokens by providing additional claims of your own.

To learn how to customize session tokens, see the [dedicated guide](/docs/backend-requests/making/custom-session-token).
To learn how to customize session tokens, see the [dedicated guide](/docs/session-requests/making/custom-session-token).
2 changes: 1 addition & 1 deletion docs/backend-requests/handling/nodejs.mdx
Original file line number Diff line number Diff line change
@@ -179,7 +179,7 @@ These options can be used with both [`ClerkExpressWithAuth`](#clerk-express-with
- `jwtKey`
- `string`

Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt).

---

2 changes: 1 addition & 1 deletion docs/deployments/clerk-cookies.mdx
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ These cookies:

- Are required for Clerk to function, and should not be blocked by you or your users.
- Do not store any personally identifiable information by default.
- Can be configured by modifying the [session token](/docs/backend-requests/resources/session-tokens) in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates).
- Can be configured by modifying the [session token](/docs/session-requests/session-tokens) in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates).

| Cookie Subgroup | Cookies | More Information |
| - | - | - |
4 changes: 2 additions & 2 deletions docs/deployments/clerk-environment-variables.mdx
Original file line number Diff line number Diff line change
@@ -77,7 +77,7 @@ The following environment variables enable you to configure API and SDK behavior
| `CLERK_JS_VERSION` | Sets the npm version for `@clerk/clerk-js`. |
| `CLERK_API_URL` | Sets the Clerk API URL for debugging. Defaults to `"https://api.clerk.com"` |
| `CLERK_API_VERSION` | Sets the version of the Clerk API to use. Defaults to `"v1"` |
| `CLERK_JWT_KEY` | Sets the JWT verification key that Clerk will use to provide networkless JWT session token verification. Refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). |
| `CLERK_JWT_KEY` | Sets the JWT verification key that Clerk will use to provide networkless JWT session token verification. Refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt). |
| `CLERK_FAPI` | Sets the URL to your Clerk apps' Frontend API. |
| `CLERK_PROXY_URL` | Sets the URL for your proxy. |
</Tab>
@@ -92,7 +92,7 @@ The following environment variables enable you to configure API and SDK behavior
| `NEXT_PUBLIC_CLERK_FAPI` | Sets the URL to your Clerk app's Frontend API. |
| `NEXT_PUBLIC_CLERK_PROXY_URL` | Sets the URL for your proxy. |
| `CLERK_ENCRYPTION_KEY` | Sets the encryption key to securely propagate `clerkMiddleware` dynamic keys during request time. A 128-bit, pseudorandom value should be used. See [Dynamic keys](/docs/references/nextjs/clerk-middleware#dynamic-keys) to learn more. |
| `CLERK_JWT_KEY` | Sets the JWT verification key that Clerk will use to provide networkless JWT session token verification. Refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). |
| `CLERK_JWT_KEY` | Sets the JWT verification key that Clerk will use to provide networkless JWT session token verification. Refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt). |
</Tab>
</Tabs>

2 changes: 1 addition & 1 deletion docs/deployments/migrate-from-firebase.mdx
Original file line number Diff line number Diff line change
@@ -141,7 +141,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be
```

> [!WARNING]
> This implementation does not take rate limiting into account. If you have a large user base, you may want to implement a retry mechanism. Clerk will return a `429` status code if you exceed the rate limit. You can find more information about Clerk's rate limits [here](/docs/backend-requests/resources/rate-limits). Keep [Firebase's rate limits](https://firebase.google.com/docs/functions/quotas) in mind as well when exporting your users.
> This implementation does not take rate limiting into account. If you have a large user base, you may want to implement a retry mechanism. Clerk will return a `429` status code if you exceed the rate limit. You can find more information about Clerk's rate limits [here](/docs/rate-limits). Keep [Firebase's rate limits](https://firebase.google.com/docs/functions/quotas) in mind as well when exporting your users.

Once the script has finished running, your user base will be fully migrated to Clerk.
</Steps>
4 changes: 2 additions & 2 deletions docs/deployments/migrate-overview.mdx
Original file line number Diff line number Diff line change
@@ -12,7 +12,7 @@ Each of these have trade-offs you'll need to consider on behalf of for your appl

## Basic export / import

With basic export / import, you're taking an export from your previous tool and importing data into Clerk. The most common way to handle this is by making use of the [`CreateUser`](/docs/reference/backend-api/tag/Users#operation/CreateUser){{ target: '_blank' }} Backend API endpoint. It's important to note that the `CreateUser` endpoint is rate limited. For more information, see the [guide on rate limits](/docs/backend-requests/resources/rate-limits#backend-api-requests).
With basic export / import, you're taking an export from your previous tool and importing data into Clerk. The most common way to handle this is by making use of the [`CreateUser`](/docs/reference/backend-api/tag/Users#operation/CreateUser){{ target: '_blank' }} Backend API endpoint. It's important to note that the `CreateUser` endpoint is rate limited. For more information, see the [guide on rate limits](/docs/rate-limits#backend-api-requests).

You'll also need to provide your `password_hasher` value (The hashing algorithm used to generate the password digest) and in some instances Clerk will transparently upgrade your users' password hashes to the more secure Bcrypt hashing algorithm. More details on this topic are available in the [Backend API reference docs](/docs/reference/backend-api/tag/Users#operation/CreateUser!path=password_hasher\&t=request){{ target: '_blank' }}.

@@ -66,7 +66,7 @@ A trickle migration is great for upgrading active users and sessions to take adv

## Migration tools

To aid in basic migrations, Clerk provides an open-source script that takes a JSON file as input, containing a list of users, and creates a user in Clerk using the Backend API. The script respects the [backend rate limits](/docs/backend-requests/resources/rate-limits#backend-api-requests) and gracefully handles errors. We suggest you customize the [Zod schema](https://github.com/clerk/migration-script/blob/main/index.ts#L25-L43){{ target: '_blank' }} to your application's needs.
To aid in basic migrations, Clerk provides an open-source script that takes a JSON file as input, containing a list of users, and creates a user in Clerk using the Backend API. The script respects the [backend rate limits](/docs/rate-limits#backend-api-requests) and gracefully handles errors. We suggest you customize the [Zod schema](https://github.com/clerk/migration-script/blob/main/index.ts#L25-L43){{ target: '_blank' }} to your application's needs.

To use Clerk's migration script, clone the [repository](https://github.com/clerk/migration-script) and follow the instructions in the `README`.

6 changes: 3 additions & 3 deletions docs/how-clerk-works/overview.mdx
Original file line number Diff line number Diff line change
@@ -255,13 +255,13 @@ The client token serves as the source of truth for authentication state. When a
### Session token

- **Cookie name:** `__session`
- **Contents:** A Clerk-signed JWT containing [a set of default claims](/docs/backend-requests/resources/session-tokens#default-session-claims). Can be customized in the Clerk Dashboard to include additional claims.
- **Domain:** Set on your application's domain directly, scoped strictly so it cannot be shared across subdomains. This is done to prevent a different app on a different subdomain from being able to take over your users' accounts. If you need to send the session token value across subdomain boundaries, such as from `example.com` to `api.example.com`, you can [put the token in a `request` header instead](/docs/backend-requests/making/cross-origin).
- **Contents:** A Clerk-signed JWT containing [a set of default claims](/docs/session-requests/session-tokens#default-session-claims). Can be customized in the Clerk Dashboard to include additional claims.
- **Domain:** Set on your application's domain directly, scoped strictly so it cannot be shared across subdomains. This is done to prevent a different app on a different subdomain from being able to take over your users' accounts. If you need to send the session token value across subdomain boundaries, such as from `example.com` to `api.example.com`, you can [put the token in a `request` header instead](/docs/session-requests/making/cross-origin).
- **Expiration:** 60 seconds
- **HttpOnly:** No - must be able to be accessed by client-side SDKs
- **SameSite:** Lax

When your app makes a request from the frontend to your backend, if the backend is on the same origin, the `__session` cookie will automatically be sent along with the request. Your backend can then [cryptographically verify](/docs/backend-requests/handling/manual-jwt) the session token's signature and extract the user ID and other claims.
When your app makes a request from the frontend to your backend, if the backend is on the same origin, the `__session` cookie will automatically be sent along with the request. Your backend can then [cryptographically verify](/docs/session-requests/handling/manual-jwt) the session token's signature and extract the user ID and other claims.

## The Handshake

4 changes: 2 additions & 2 deletions docs/how-clerk-works/tokens-signatures.mdx
Original file line number Diff line number Diff line change
@@ -62,7 +62,7 @@ Let's decode and break down each part:
}
```

**Payload**: The payload contains the actual information that you want to send. In Clerk's case, this includes information about the authenticated user. [Read more about Clerk's session JWT payload](/docs/backend-requests/resources/session-tokens).
**Payload**: The payload contains the actual information that you want to send. In Clerk's case, this includes information about the authenticated user. [Read more about Clerk's session JWT payload](/docs/session-requests/session-tokens).

```json
{
@@ -77,7 +77,7 @@ Let's decode and break down each part:
Error: The string is not correctly encoded
```

When decoding the signature from base64, an error is thrown because the signature is not base64-encoded. This is expected behavior. The recipient must use the JWT issuer's public key and the algorithm specified in the header (e.g., RS256) to verify the signature. Clerk's SDKs all ship with a method for verifying the signature of a Clerk JWT: [`authenticateRequest()`](/docs/references/backend/authenticate-request). But if you'd like to verify the signature yourself, see the [guide on manual JWT verification](/docs/backend-requests/handling/manual-jwt).
When decoding the signature from base64, an error is thrown because the signature is not base64-encoded. This is expected behavior. The recipient must use the JWT issuer's public key and the algorithm specified in the header (e.g., RS256) to verify the signature. Clerk's SDKs all ship with a method for verifying the signature of a Clerk JWT: [`authenticateRequest()`](/docs/references/backend/authenticate-request). But if you'd like to verify the signature yourself, see the [guide on manual JWT verification](/docs/session-requests/handling/manual-jwt).

### How Clerk uses JWTs

2 changes: 1 addition & 1 deletion docs/integrations/databases/convex.mdx
Original file line number Diff line number Diff line change
@@ -39,7 +39,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q

![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/convex/create-template.webp)

The Convex template will pre-populate the default audience (`aud`) claim required by Convex. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.
The Convex template will pre-populate the default audience (`aud`) claim required by Convex. You can include additional claims as necessary. [Shortcodes](/docs/session-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.

![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/convex/template-shortcodes.webp)

4 changes: 2 additions & 2 deletions docs/integrations/databases/fauna.mdx
Original file line number Diff line number Diff line change
@@ -86,8 +86,8 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your
1. Select the **New template** button, then select **Fauna** from the list of options.
1. Configure your template:
- The value of the **Name** field will be required when using the template in your code. For this tutorial, name it `fauna`.
- You can leave all other fields as their default settings or customize them to your needs. See the [JWT template guide](/docs/backend-requests/making/jwt-templates#creating-a-template) to learn more about these settings.
- In the **Claims** section, set the `aud` claim to the **Audience URL** you copied from Fauna in Step 2. The URL format should be `https://db.fauna.com/db/<YOUR_FAUNA_DB_ID>`. You can include additional claims if you’d like, but `aud` is the only required one. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.
- You can leave all other fields as their default settings or customize them to your needs. See the [JWT template guide](/docs/session-requests/making/jwt-templates#creating-a-template) to learn more about these settings.
- In the **Claims** section, set the `aud` claim to the **Audience URL** you copied from Fauna in Step 2. The URL format should be `https://db.fauna.com/db/<YOUR_FAUNA_DB_ID>`. You can include additional claims if you’d like, but `aud` is the only required one. [Shortcodes](/docs/session-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.
- Select **Save** from the notification bubble to complete setup.

## Install the Fauna library
2 changes: 1 addition & 1 deletion docs/integrations/databases/grafbase.mdx
Original file line number Diff line number Diff line change
@@ -13,7 +13,7 @@ Once the Grafbase template is created, you will be redirected to the template's

![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/grafbase/create-template.webp)

The Grafbase template will pre-populate the default claims required by Grafbase. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.
The Grafbase template will pre-populate the default claims required by Grafbase. You can include additional claims as necessary. [Shortcodes](/docs/session-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.

> [!NOTE]
> If your GraphQL API restricts access based on groups, you’ll need to specify the users groups in the `groups` claim.
2 changes: 1 addition & 1 deletion docs/integrations/databases/hasura.mdx
Original file line number Diff line number Diff line change
@@ -13,7 +13,7 @@ Once the Hasura template is created, you will be redirected to the template's pa

![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/hasura/create-template.webp)

The Hasura template will pre-populate the default claims required by Hasura. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.
The Hasura template will pre-populate the default claims required by Hasura. You can include additional claims as necessary. [Shortcodes](/docs/session-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy.

![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/hasura/template-shortcodes.webp)

Loading