diff --git a/docs/_partials/clerk-middleware-options.mdx b/docs/_partials/clerk-middleware-options.mdx index 27065982e4..aa8e232ce0 100644 --- a/docs/_partials/clerk-middleware-options.mdx +++ b/docs/_partials/clerk-middleware-options.mdx @@ -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). --- diff --git a/docs/_partials/clerk-options.mdx b/docs/_partials/clerk-options.mdx index e105bfc724..bf9020cd33 100644 --- a/docs/_partials/clerk-options.mdx +++ b/docs/_partials/clerk-options.mdx @@ -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). --- diff --git a/docs/_partials/root-auth-loader.mdx b/docs/_partials/root-auth-loader.mdx index 56123d9692..7d7586e8e7 100644 --- a/docs/_partials/root-auth-loader.mdx +++ b/docs/_partials/root-auth-loader.mdx @@ -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). --- diff --git a/docs/_partials/token-size-callout.mdx b/docs/_partials/token-size-callout.mdx index 5511b0eeaf..3f33211eae 100644 --- a/docs/_partials/token-size-callout.mdx +++ b/docs/_partials/token-size-callout.mdx @@ -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). diff --git a/docs/authentication/configuration/session-options.mdx b/docs/authentication/configuration/session-options.mdx index 65644e5cb4..04a3793f79 100644 --- a/docs/authentication/configuration/session-options.mdx +++ b/docs/authentication/configuration/session-options.mdx @@ -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). diff --git a/docs/backend-requests/handling/nodejs.mdx b/docs/backend-requests/handling/nodejs.mdx index 836ffb0d5b..2a70abdfea 100644 --- a/docs/backend-requests/handling/nodejs.mdx +++ b/docs/backend-requests/handling/nodejs.mdx @@ -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). --- diff --git a/docs/deployments/clerk-cookies.mdx b/docs/deployments/clerk-cookies.mdx index 828b45b9bb..769d0613c6 100644 --- a/docs/deployments/clerk-cookies.mdx +++ b/docs/deployments/clerk-cookies.mdx @@ -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 | | - | - | - | diff --git a/docs/deployments/clerk-environment-variables.mdx b/docs/deployments/clerk-environment-variables.mdx index adff97625e..ea0140349a 100644 --- a/docs/deployments/clerk-environment-variables.mdx +++ b/docs/deployments/clerk-environment-variables.mdx @@ -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. | @@ -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). | diff --git a/docs/deployments/migrate-from-firebase.mdx b/docs/deployments/migrate-from-firebase.mdx index 328959722d..022d57697a 100644 --- a/docs/deployments/migrate-from-firebase.mdx +++ b/docs/deployments/migrate-from-firebase.mdx @@ -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. diff --git a/docs/deployments/migrate-overview.mdx b/docs/deployments/migrate-overview.mdx index 2e34ef1b3b..e6a9628c4a 100644 --- a/docs/deployments/migrate-overview.mdx +++ b/docs/deployments/migrate-overview.mdx @@ -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`. diff --git a/docs/how-clerk-works/overview.mdx b/docs/how-clerk-works/overview.mdx index 97e960960a..87177844f6 100644 --- a/docs/how-clerk-works/overview.mdx +++ b/docs/how-clerk-works/overview.mdx @@ -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 diff --git a/docs/how-clerk-works/tokens-signatures.mdx b/docs/how-clerk-works/tokens-signatures.mdx index 097b94a9b4..a4221f2642 100644 --- a/docs/how-clerk-works/tokens-signatures.mdx +++ b/docs/how-clerk-works/tokens-signatures.mdx @@ -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 diff --git a/docs/integrations/databases/convex.mdx b/docs/integrations/databases/convex.mdx index bbce2b5bc4..6aa0913897 100644 --- a/docs/integrations/databases/convex.mdx +++ b/docs/integrations/databases/convex.mdx @@ -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) diff --git a/docs/integrations/databases/fauna.mdx b/docs/integrations/databases/fauna.mdx index 0e01ef4f9f..ca656cc8c6 100644 --- a/docs/integrations/databases/fauna.mdx +++ b/docs/integrations/databases/fauna.mdx @@ -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/`. 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/`. 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 diff --git a/docs/integrations/databases/grafbase.mdx b/docs/integrations/databases/grafbase.mdx index 018c84b5ad..c252a59496 100644 --- a/docs/integrations/databases/grafbase.mdx +++ b/docs/integrations/databases/grafbase.mdx @@ -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. diff --git a/docs/integrations/databases/hasura.mdx b/docs/integrations/databases/hasura.mdx index 50b25dd68e..0bfc703645 100644 --- a/docs/integrations/databases/hasura.mdx +++ b/docs/integrations/databases/hasura.mdx @@ -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) diff --git a/docs/integrations/databases/instantdb.mdx b/docs/integrations/databases/instantdb.mdx index b72937377c..f12dfa5d3f 100644 --- a/docs/integrations/databases/instantdb.mdx +++ b/docs/integrations/databases/instantdb.mdx @@ -37,7 +37,7 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in ## Configure your Clerk session token - InstantDB uses Clerk's [session token](/docs/backend-requests/resources/session-tokens) to authenticate users. To use InstantDB with Clerk, you need to include the `email` claim in your session token. + InstantDB uses Clerk's [session token](/docs/session-requests/session-tokens) to authenticate users. To use InstantDB with Clerk, you need to include the `email` claim in your session token. 1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. In the **Customize session token** section, select **Edit**. diff --git a/docs/integrations/databases/nhost.mdx b/docs/integrations/databases/nhost.mdx index b036fb49fb..1274540479 100644 --- a/docs/integrations/databases/nhost.mdx +++ b/docs/integrations/databases/nhost.mdx @@ -13,7 +13,7 @@ Once the Nhost template is created, you will be redirected to the template's pag ![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/nhost/create-template.webp) -The Nhost template will pre-populate the default claims required by Nhost and 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 Nhost template will pre-populate the default claims required by Nhost and 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/nhost/template-shortcodes.webp) diff --git a/docs/integrations/databases/supabase.mdx b/docs/integrations/databases/supabase.mdx index 5e07259eef..e0c5dbbba7 100644 --- a/docs/integrations/databases/supabase.mdx +++ b/docs/integrations/databases/supabase.mdx @@ -186,7 +186,7 @@ For interacting with the Supabase dashboard, you can either use the **Supabase i - The value of the **Name** field will be required when using the template in your code. For this tutorial, name it `supabase`. - **Signing algorithm** will be `HS256` by default. This algorithm is required to use JWTs with Supabase. [Learn more in their docs](https://supabase.com/docs/guides/resources/glossary#jwt-signing-secret). - Under **Signing key**, add the value of your Supabase **JWT Secret Key** from [the previous step](#get-your-supabase-jwt-secret-key). - - You can leave all other fields at 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. + - You can leave all other fields at 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. - Select **Save** from the notification bubble to complete setup. ### Install the Supabase client library diff --git a/docs/machine-requests/machine-tokens.mdx b/docs/machine-requests/machine-tokens.mdx new file mode 100644 index 0000000000..baa77f86f1 --- /dev/null +++ b/docs/machine-requests/machine-tokens.mdx @@ -0,0 +1,65 @@ +--- +title: Machine tokens +description: Learn about machine tokens and how to validate them in your backend. +--- + +**Machine tokens** are JWTs used to authenticate machine requests your application makes. + +They are similiar to [session tokens](/docs/session-requests/session-tokens) however, unlike session tokens, machine tokens are not associated with a user. Instead **you** are responsible for determining the identity of the machine making the request. + +## Creating machine tokens + +### Machine ID + +Every machine token you create needs to be associated with a `machine_id`. You can pick any value for the `machine_id` as long as it meets the following requirements: + +- It must be prefixed with `mch_` +- It must only contain lowercase letters and numbers +- It must be 96 characters or less + +> [!TIP] +> It is a good idea to have the `machine_id` correspond with the identity of the service generating the token. For example if you have a cron service, a `machine_id` of `mch_cron` would make sense. + +- Examples: + - ✅ `mch_cron_service` + - ✅ `mch_background_worker` + - ✅ `mch_device_6580fc77_afca_47ac_8973_b7261d14e4c7` + - ❌ `user_2p94zsO6sBvVZR5Ca0KfBNLM36Z` + - ❌ `mch-invalid` + - ❌ `MCH_UPPERCASE` + +### Claims + +You can add custom claims to your machine token to include any additional information that your application might need. Claims are key-value pairs included in the token's payload, and they can convey important data such as permissions, roles, or any other attributes relevant to the machine's identity. + +For example, it is a good practice to include any permissions that your service requires directly in the claims. This allows your backend to easily verify what actions the machine is authorized to perform. + +> [!NOTE] +> There are already claims set by Clerk. You cannot override claims [already set by Clerk](#default-machine-claims). + +### Expires In Seconds + +The `expiresInSeconds` parameter defines how long the machine token remains valid, specified in seconds. This parameter is optional and defaults to 60 seconds (1 minute). + +If you need the machine token to be valid for a longer period of time, you can set the `expiresInSeconds` parameter to a higher value. However, because machine tokens are JWTs, longer-lived tokens can present a higher security risk if compromised, while shorter-lived tokens may require more frequent token generation, potentially impacting your [Backend API rate limits](/docs/rate-limits). Therefore, it's important to balance token lifespan with security requirements and rate limit considerations. + +### Clock Skew + +The `allowedClockSkew` parameter provides a leeway in seconds to account for clock differences between servers. This setting affects the `nbf` (Not Before) claim in the token, calculated as `nbf = current_time - allowed_clock_skew`. The default value is 5 seconds. + +Adjusting the clock skew helps prevent token validation failures due to minor time discrepancies between the issuing server and the verifying server. + +## Default machine claims + +Every generated token has default claims that cannot be overridden by custom claims. Clerk's default claims include: + +- `exp`: expiration time - the time after which the token will expire, as a Unix timestamp. Determined using the **Token Expires In Seconds** request body parameter when creating machine tokens. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information. +- `iat`: issued at - the time at which the token was issued as a Unix timestamp. For example: `1516239022`. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information. +- `jti`: JWT ID - the ID of the token internally generated by Clerk. For example: `a1b2c3d4e5f67890abcd`. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7) for more information. +- `iss`: issuer - the Frontend API URL of your instance. For example: `https://clerk.your-site.com` for a production instance or `https://your-site.clerk.accounts.dev` for a development instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information. +- `nbf`: not before - the time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** request body parameter when creating machine tokens. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information. +- `sub`: subject - the ID of the machine that created the token. Determined using the **Machine ID** request body parameter when creating machine tokens. For example: `mch_123`. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. + +## Using Machine Tokens to create and verify requests + +To start using machine tokens to create and verify requests, refer to [making machine requests](/docs/machine-requests/overview). diff --git a/docs/machine-requests/manual-jwt.mdx b/docs/machine-requests/manual-jwt.mdx new file mode 100644 index 0000000000..0fe86f8fbe --- /dev/null +++ b/docs/machine-requests/manual-jwt.mdx @@ -0,0 +1,133 @@ +--- +title: Manual JWT verification +description: Learn how to manually verify Clerk-generated machine tokens (JWTs). +--- + +Your Clerk-generated [machine tokens](/docs/machine-requests/machine-tokens) are JWTs which are signed using your instance's private key and can be verified using your instance's public key. + +For every machine request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). Additionally, you might want to differentiate between machine and user requests within your application. If these validations succeed, then the machine is authenticated and granted access to your application. + +> [!TIP] +> To differentiate between a machine token and user token, the `sub` claim in a machine token starts with `mch_` instead of `user_` on a session token. + +The `authenticateRequest()` method from the JavaScript Backend SDK handles these validations for you. Alternatively, you can manually verify the token without using the SDK. See the following sections for more information. + +## Use `authenticateRequest()` to verify a machine token + +The [`authenticateRequest()`](/docs/references/backend/authenticate-request) method from the JavaScript Backend SDK accepts the `request` object, and by using the `entity: "machine"` option, you can authenticate the request _as a machine request_ instead of the default _user request_. + +For more information, including usage with higher-level SDKs, see the [`authenticateRequest()` reference](/docs/references/backend/authenticate-request). + +For example, the following code snippet uses the `authenticateRequest()` method to verify a machine token in a simple node http server. + +```tsx +import { createClerkClient } from '@clerk/backend' +import http from 'http' + +const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }) + +const server = http.createServer(async (req, res) => { + try { + const { isMachineAuthenticated } = await clerk.authenticateRequest(req, { + entity: 'machine', + }) + + if (!isMachineAuthenticated) { + res.writeHead(401) + res.end(JSON.stringify({ message: 'Unauthorized' })) + return + } + + await runCronJob() + + res.writeHead(200) + res.end(JSON.stringify({ message: 'Success' })) + } catch (err) { + res.writeHead(500) + res.end(JSON.stringify({ message: 'Internal Server Error' })) + } +}) + +server.listen(3000, () => { + console.log('Server running on port 3000') +}) +``` + +## Manually verify a machine token + + + ### Retrieve the machine token + + Retrieve the machine token from the `Authorization` header. + + ### Get your instance's public key + + Use one of the three ways to obtain your public key: + + 1. Use the Backend API in JSON Web Key Set (JWKS) format at the following endpoint [https://api.clerk.com/v1/jwks](https://clerk.com/docs/reference/backend-api/tag/JWKS#operation/GetJWKS). + 1. Use your **Frontend API URL** in JWKS format, also known as **JWKS URL**. The format is `https:///.well-known/jwks.json`. To retrieve your **JWKS URL**, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and select **Show JWT public key**. + 1. Use your **PEM Public Key**. To retrieve it, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and select **Show JWT Public Key**. + + ### Verify the token signature + + To verify the token signature: + + 1. Use your instance's public key to verify the token's signature. + 1. Validate that the token isn't expired by checking the `exp` ([expiration time](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)) and `nbf` ([not before](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5)) claims. + 1. Validate that the `sub` (subject) claim starts with `mch_`. This ensures the token is a machine token and not a session token. + + ### Finished + + If the above process succeeds, the machine is considered authenticated to make requests to your application. You can also retrieve the machine ID from the token's `sub` claim. + + +### Example + +The following example manually verifies a machine token. + +```tsx +import jwt from 'jsonwebtoken' + +export default async function verifyMachineToken(req: Request, res: Response) { + // Your public key should be set as an environment variable + const publicKey = process.env.CLERK_PEM_PUBLIC_KEY + + // Get the machine token from the Authorization header + const authHeader = req.headers.authorization + if (!authHeader) { + res.status(401).json({ error: 'No machine token provided' }) + return + } + + // Remove 'Bearer ' prefix if present + const token = authHeader.replace('Bearer ', '') + + try { + const options = { algorithms: ['RS256'] } + const decoded = jwt.verify(token, publicKey, options) + + // Validate the token's expiration (exp) and not before (nbf) claims + const currentTime = Math.floor(Date.now() / 1000) + if (decoded.exp < currentTime || decoded.nbf > currentTime) { + throw new Error('Token is expired or not yet valid') + } + + // Validate that this is a machine token by checking the sub claim + if (!decoded.sub?.startsWith('mch_')) { + throw new Error('Not a valid machine token') + } + + // The machine is authenticated. You can get the machine ID from the sub claim + const machineId = decoded.sub + + res.status(200).json({ + machineId, + claims: decoded, + }) + } catch (error) { + res.status(401).json({ + error: error.message, + }) + } +} +``` diff --git a/docs/machine-requests/overview.mdx b/docs/machine-requests/overview.mdx new file mode 100644 index 0000000000..cee1de18cd --- /dev/null +++ b/docs/machine-requests/overview.mdx @@ -0,0 +1,111 @@ +--- +title: Machine-to-Machine Requests +description: Learn how to use machine tokens to make and verify authenticated requests. +--- + +Machine-to-machine (M2M) authentication allows services, scripts, or devices to securely communicate with each other without the need for a user's session. + +For example, you might need machine tokens for: + +- Cron jobs that update your database +- Background workers processing queued tasks +- Microservices communicating with each other + +## Creating Machine Requests + +You can create a machine token using the [Clerk Backend API](https://clerk.com/docs/reference/backend-api/tag/machine-tokens). Then use the created token in the `Authorization` header of outgoing requests. + +> [!WARNING] +> Creating machine tokens uses the Clerk Backend API, and so it is subject to the [Backend API rate limits](/docs/rate-limits). + +### Example using the Clerk JavaScript Backend SDK + +```tsx +import { createClerkClient } from '@clerk/backend' + +export default async function cronJob() { + const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }) + + const { jwt } = await clerkClient.machineTokens.create({ + machineId: 'mch_cron', + claims: { + permissions: ['read', 'write'], + }, + expiresInSeconds: 60, + }) + + await fetch('https://api.example.com/cron', { + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + }, + body: JSON.stringify({ + message: 'Hello World!', + }), + }) +} +``` + +## Verifying Machine Requests + +For a Machine Request to be valid, it must include a valid [machine token](/docs/machine-requests/machine-tokens) in the Bearer `Authorization` header. + +You can verify machine tokens in two ways: + +1. Using Clerk's Backend SDKs (recommended) +1. Manually verifying the machine token JWT using your instance's Public Key. + +### Using Clerk's Backend SDKs + +By default, authenticating requests will default to authenticating them as user [session requests](/docs/session-requests/overview). + +For machine requests, you can use the `entity: 'machine'` option to authenticate requests. + +> [!WARNING] +> The `entity: 'machine'` option is only available in the Clerk Next.js SDK and Clerk Backend Javascript SDK during the beta. + +#### Examples + + + + ```tsx import { auth } from '@clerk/nextjs/server'; + import { NextResponse } from 'next/server' + import { runCronJob } from './cronJob' + + export const POST = async () => { + const { machineId } = await auth({ entity: 'machine' }) + + if (!machineId) { + return NextResponse.json({ message: 'Unauthorized' }, { status: 401 }) + } + + await runCronJob() + + return NextResponse.json({ message: 'Cron job ran' }) + } + ``` + + + + ```tsx import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server"; + const isMachineRoute = createRouteMatcher(['/api/cron']) + + export default clerkMiddleware(async (auth, req) => { + if (isMachineRoute(req)) { + const { isMachineAuthenticated } = await auth({ entity: 'machine' }) + if (!isMachineAuthenticated) { + return new Response('Unauthorized', { status: 401 }) + } + } + }) + + export const config = { + matcher: ['/((?!.*\\..*|_next).*)', '/'], + } + ``` + + + +### Manually verifying the machine token JWT + +See the [manual JWT verification](/docs/machine-requests/manual-jwt) guide for more information. diff --git a/docs/manifest.json b/docs/manifest.json index eaa9922b52..bb3ea0b20b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2658,13 +2658,56 @@ ] }, { - "title": "Backend Requests", + "title": "Webhooks", + "collapse": true, + "items": [ + [ + { + "title": "Overview", + "href": "/docs/webhooks/overview" + }, + { + "title": "Sync Clerk data to your application with webhooks", + "href": "/docs/webhooks/sync-data" + }, + { + "title": "Handling webhooks with Inngest", + "href": "/docs/webhooks/inngest" + }, + { + "title": "Send webhooks to Loops", + "href": "/docs/webhooks/loops" + }, + { + "title": "Debug your webhooks", + "href": "/docs/webhooks/debug-your-webhooks" + } + ] + ] + }, + { + "title": "Transfer ownership", + "href": "/docs/guides/transferring-your-app" + } + ] + ] + }, + { + "title": "Backend requests", + "items": [ + [ + { + "title": "Session Requests", "collapse": true, "items": [ [ { "title": "Overview", - "href": "/docs/backend-requests/overview" + "href": "/docs/session-requests/overview" + }, + { + "title": "Session tokens", + "href": "/docs/session-requests/session-tokens" }, { "title": "Making requests", @@ -2672,19 +2715,19 @@ [ { "title": "Same-Origin Requests", - "href": "/docs/backend-requests/making/same-origin" + "href": "/docs/session-requests/making/same-origin" }, { "title": "Cross-Origin Requests", - "href": "/docs/backend-requests/making/cross-origin" + "href": "/docs/session-requests/making/cross-origin" }, { "title": "Customize your session token", - "href": "/docs/backend-requests/making/custom-session-token" + "href": "/docs/session-requests/making/custom-session-token" }, { "title": "JWT templates", - "href": "/docs/backend-requests/making/jwt-templates" + "href": "/docs/session-requests/making/jwt-templates" } ] ] @@ -2695,47 +2738,17 @@ [ { "title": "Go", - "href": "/docs/backend-requests/handling/go", + "href": "/docs/session-requests/handling/go", "icon": "go" }, { "title": "Ruby / Rails", - "href": "/docs/backend-requests/handling/ruby-rails", + "href": "/docs/session-requests/handling/ruby-rails", "icon": "ruby" }, { "title": "Manual JWT Verification", - "href": "/docs/backend-requests/handling/manual-jwt" - } - ] - ] - }, - { - "title": "Versioning", - "items": [ - [ - { - "title": "Overview", - "href": "/docs/backend-requests/versioning/overview" - }, - { - "title": "Available versions", - "href": "/docs/backend-requests/versioning/available-versions" - } - ] - ] - }, - { - "title": "Resources", - "items": [ - [ - { - "title": "Session tokens", - "href": "/docs/backend-requests/resources/session-tokens" - }, - { - "title": "Rate limits", - "href": "/docs/backend-requests/resources/rate-limits" + "href": "/docs/session-requests/handling/manual-jwt" } ] ] @@ -2744,36 +2757,45 @@ ] }, { - "title": "Webhooks", + "title": "Machine Requests", "collapse": true, + "tag": "(Beta)", "items": [ [ { "title": "Overview", - "href": "/docs/webhooks/overview" + "href": "/docs/machine-requests/overview" }, { - "title": "Sync Clerk data to your application with webhooks", - "href": "/docs/webhooks/sync-data" + "title": "Machine tokens", + "href": "/docs/machine-requests/machine-tokens" }, { - "title": "Handling webhooks with Inngest", - "href": "/docs/webhooks/inngest" - }, + "title": "Manual JWT Verification", + "href": "/docs/machine-requests/manual-jwt" + } + ] + ] + }, + { + "title": "Versioning", + "collapse": true, + "items": [ + [ { - "title": "Send webhooks to Loops", - "href": "/docs/webhooks/loops" + "title": "Overview", + "href": "/docs/versioning/overview" }, { - "title": "Debug your webhooks", - "href": "/docs/webhooks/debug-your-webhooks" + "title": "Available versions", + "href": "/docs/versioning/available-versions" } ] ] }, { - "title": "Transfer ownership", - "href": "/docs/guides/transferring-your-app" + "title": "Rate limits", + "href": "/docs/rate-limits" } ] ] diff --git a/docs/organizations/org-slugs-in-urls.mdx b/docs/organizations/org-slugs-in-urls.mdx index a6e76c4160..ffa1a084f8 100644 --- a/docs/organizations/org-slugs-in-urls.mdx +++ b/docs/organizations/org-slugs-in-urls.mdx @@ -229,7 +229,7 @@ This guide shows you how to add organization slugs to your app's URLs, configure To get organization information on the server-side, access the [`Auth`](/docs/references/backend/types/auth-object) object. In Next.js apps, this object is returned by [`auth()`](/docs/references/nextjs/auth). In other frameworks, use the [`getAuth()`](/docs/references/nextjs/get-auth) helper to get the `Auth` object. - To access additional organization information like the organization name, you'll need to [customize the Clerk session token](/docs/backend-requests/making/custom-session-token) to include these details: + To access additional organization information like the organization name, you'll need to [customize the Clerk session token](/docs/session-requests/making/custom-session-token) to include these details: 1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. In the **Customize session token** section, select **Edit**. diff --git a/docs/organizations/roles-permissions.mdx b/docs/organizations/roles-permissions.mdx index ee0ed574ac..1bfe49b48b 100644 --- a/docs/organizations/roles-permissions.mdx +++ b/docs/organizations/roles-permissions.mdx @@ -61,7 +61,7 @@ Clerk's system permissions consist of the following: You can assign these system permissions to any role. > [!WARNING] -> System permissions aren't included in [session claims](/docs/backend-requests/resources/session-tokens#default-session-claims). To check permissions on the server-side, you must [create custom permissions](/docs/organizations/create-roles-permissions). +> System permissions aren't included in [session claims](/docs/session-requests/session-tokens#default-session-claims). To check permissions on the server-side, you must [create custom permissions](/docs/organizations/create-roles-permissions). ### Custom permissions diff --git a/docs/backend-requests/resources/rate-limits.mdx b/docs/rate-limits.mdx similarity index 100% rename from docs/backend-requests/resources/rate-limits.mdx rename to docs/rate-limits.mdx diff --git a/docs/references/astro/locals.mdx b/docs/references/astro/locals.mdx index a7c7d8a8c3..4361d3e586 100644 --- a/docs/references/astro/locals.mdx +++ b/docs/references/astro/locals.mdx @@ -54,7 +54,7 @@ Current user data is important for data enrichment. You can use the `currentUser Under the hood, this local: - uses the `GET /v1/users/me` endpoint. -- counts towards the [Backend API Request Rate Limit](/docs/backend-requests/resources/rate-limits#rate-limits). +- counts towards the [Backend API Request Rate Limit](/docs/rate-limits#rate-limits). For more information on `currentUser()`, see the [reference](/docs/references/nextjs/current-user){{ target: '_blank' }}. diff --git a/docs/references/backend/authenticate-request.mdx b/docs/references/backend/authenticate-request.mdx index e029cab0c8..67f3eaa5d1 100644 --- a/docs/references/backend/authenticate-request.mdx +++ b/docs/references/backend/authenticate-request.mdx @@ -57,7 +57,14 @@ It is recommended to set these options as [environment variables](/docs/deployme - `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. 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. For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt). + + --- + + - `entity?` + - `user` | `machine` | `any` + + Determines what type of authentication to perform. If set to `user`, the function will authenticate a user session. If set to `machine`, the function will authenticate a machine-to-machine request. If set to `any`, the function will authenticate both user sessions and machine-to-machine requests. Defaults to `user`. --- @@ -198,6 +205,34 @@ export async function GET(req: Request) { } ``` +### Machine-to-machine authentication + +By default, `authenticateRequest()` will authenticate a [session request](/docs/session-requests/overview). To authenticate a machine-to-machine request, you need to set the `entity` option to `machine`. +Read more about [machine-to-machine authentication](/docs/machine-requests/overview). + +```tsx +import { createClerkClient } from '@clerk/backend' + +export async function GET(req: Request) { + const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY, + publishableKey: process.env.CLERK_PUBLISHABLE_KEY, + }) + + const { isMachineAuthenticated } = await clerkClient.authenticateRequest(req, { + entity: 'machine', + }) + + if (!isMachineAuthenticated) { + return Response.json({ status: 401 }) + } + + // Add logic to perform protected actions + + return Response.json({ message: 'This is a machine-to-machine reply' }) +} +``` + ### Networkless token verification {/* Note: this example is duped from /authenticate-request. Probably a good opportunity to use a partial here */} diff --git a/docs/references/backend/sessions/verify-session.mdx b/docs/references/backend/sessions/verify-session.mdx index 36fd248cfc..b404b22733 100644 --- a/docs/references/backend/sessions/verify-session.mdx +++ b/docs/references/backend/sessions/verify-session.mdx @@ -4,7 +4,7 @@ description: Use Clerk's Backend SDK to to verify whether a session with a given --- > [!CAUTION] -> This method is now deprecated. Refer to the [Manual JWT Verification](/docs/backend-requests/handling/manual-jwt) guide for the recommended way to verify sessions/tokens. +> This method is now deprecated. Refer to the [Manual JWT Verification](/docs/session-requests/handling/manual-jwt) guide for the recommended way to verify sessions/tokens. Verifies whether a session with a given ID corresponds to the provided session token. Throws an error if the provided ID is invalid. diff --git a/docs/references/backend/types/auth-object.mdx b/docs/references/backend/types/auth-object.mdx index a6233a71a1..39f9bf9d50 100644 --- a/docs/references/backend/types/auth-object.mdx +++ b/docs/references/backend/types/auth-object.mdx @@ -1,9 +1,9 @@ --- title: Auth object -description: The Auth object contains information about the current user's session. +description: The Auth object contains information about a signed-in user or an authenticated machine request. --- -The `Auth` object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token. +The `Auth` object contains important information about an authenticated request. This includes a user's session ID, user ID, and organization ID. Or if the request is from a [machine](/docs/machine-requests/overview), it contains the machine's ID and machine token claims. ## How to access the `Auth` object @@ -20,7 +20,36 @@ The `Auth` object is available on the `request` object in server contexts. Some | Tanstack Start | [`getAuth()`](/docs/references/tanstack-start/get-auth) | | Other | `request.auth` | -## Properties +Depending on the request, the `Auth` object will contain different properties. + +- If the request wasn't authenticated, the `Auth` object will be empty. +- If the request is from a signed-in user, the `Auth` object will contain [properties for that user](/docs/references/backend/types/auth-object#signed-in-user-properties). +- If the request is from a machine, the `Auth` object will contain [properties for that machine request](/docs/references/backend/types/auth-object#machine-request-properties). + +## Machine request properties + + + - `machineId` + - `string` + + The ID of the machine, created by the [machine token](/docs/machine-requests/machine-tokens). + + --- + + - `claims` + - `JwtPayload` + + Custom claims from the [machine token](/docs/machine-requests/machine-tokens). + + --- + + - `entity` + - `machine` + + The type of the authenticated entity. + + +## Signed-in user properties - `sessionId` @@ -68,7 +97,7 @@ The `Auth` object is available on the `request` object in server contexts. Some - `sessionClaims` - `JwtPayload` - The current user's [session claims](/docs/backend-requests/resources/session-tokens#default-session-claims). + The current user's [session claims](/docs/session-requests/session-tokens#default-session-claims). --- @@ -79,6 +108,15 @@ The `Auth` object is available on the `request` object in server contexts. Some --- + --- + + - `entity` + - `user` + + The type of the authenticated entity. + + --- + - [`has()`](#has) - (isAuthorizedParams: [CheckAuthorizationParamsWithCustomPermissions](#check-authorization-params-with-custom-permissions)) => boolean @@ -96,7 +134,7 @@ The `Auth` object is available on the `request` object in server contexts. Some - [`getToken()`](#get-token) - [`ServerGetToken`](#server-get-token) - A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/making/jwt-templates). + A function that gets the current user's [session token](/docs/session-requests/session-tokens) or a [custom JWT template](/docs/session-requests/making/jwt-templates). --- @@ -237,7 +275,7 @@ You can use `has()` to check if a user has verified their credentials within a c ### `getToken()` -`getToken()` retrieves the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/making/jwt-templates). +`getToken()` retrieves the current user's [session token](/docs/session-requests/session-tokens) or a [custom JWT template](/docs/session-requests/making/jwt-templates). ```typescript const getToken: ServerGetToken @@ -461,3 +499,21 @@ The following is an example of the `Auth` object with an active organization: }, } ``` + +## `Auth` object example of a machine request + +```js {{ mark: [8], prettier: false }} +{ + machineId: 'mch_cron_job', + claims: { + azp: 'http://localhost:3000', + exp: 1666622607, + iat: 1666622547, + iss: 'https://clerk.quiet.muskox-85.lcl.dev', + nbf: 1666622537, + sid: 'sess_123', + sub: 'user_123', + some_custom_claim: 'some_value', + }, +} +``` diff --git a/docs/references/backend/verify-token.mdx b/docs/references/backend/verify-token.mdx index b2fdd304a9..640eb06d25 100644 --- a/docs/references/backend/verify-token.mdx +++ b/docs/references/backend/verify-token.mdx @@ -65,7 +65,7 @@ It is recommended to set these options as [environment variables](/docs/deployme - `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. 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. For more information, refer to [Manual JWT verification](/docs/session-requests/handling/manual-jwt). --- diff --git a/docs/references/ios/get-token.mdx b/docs/references/ios/get-token.mdx index a4a2f5fbcc..76a7a29c4f 100644 --- a/docs/references/ios/get-token.mdx +++ b/docs/references/ios/get-token.mdx @@ -3,7 +3,7 @@ title: '`getToken()`' description: Use Clerk's iOS SDK to retrieve a token for a JWT template that is defined in the Clerk Dashboard. --- -The `getToken()` method retrieves the user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/making/jwt-templates). +The `getToken()` method retrieves the user's [session token](/docs/session-requests/session-tokens) or a [custom JWT template](/docs/session-requests/making/jwt-templates). This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for a Clerk token is one minute. diff --git a/docs/references/javascript/session.mdx b/docs/references/javascript/session.mdx index 7a0b0fb3f5..5c655efa98 100644 --- a/docs/references/javascript/session.mdx +++ b/docs/references/javascript/session.mdx @@ -137,7 +137,7 @@ function touch(): Promise ### `getToken()` -Retrieves the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/making/jwt-templates). +Retrieves the current user's [session token](/docs/session-requests/session-tokens) or a [custom JWT template](/docs/session-requests/making/jwt-templates). This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for a Clerk token is one minute. diff --git a/docs/references/nextjs/add-onboarding-flow.mdx b/docs/references/nextjs/add-onboarding-flow.mdx index 62a9c15bb8..668e692138 100644 --- a/docs/references/nextjs/add-onboarding-flow.mdx +++ b/docs/references/nextjs/add-onboarding-flow.mdx @@ -20,7 +20,7 @@ For the sake of this guide, examples are written for Next.js App Router, but can ## Add custom claims to your session token -[Session tokens](/docs/backend-requests/resources/session-tokens) are JWTs that are generated by Clerk on behalf of your instance, and contain claims that allow you to store data about a user's session. With Clerk, when a session token exists for a user, it indicates that the user is authenticated, and the associated claims can be retrieved at any time. +[Session tokens](/docs/session-requests/session-tokens) are JWTs that are generated by Clerk on behalf of your instance, and contain claims that allow you to store data about a user's session. With Clerk, when a session token exists for a user, it indicates that the user is authenticated, and the associated claims can be retrieved at any time. For this guide, you will use an `onboardingComplete` property in the user's public metadata to track their onboarding status. But first, you need to add a custom claim to the session token that will allow you to access the user's public metadata in your Middleware. diff --git a/docs/references/nextjs/auth.mdx b/docs/references/nextjs/auth.mdx index 940531c800..2febdd09b1 100644 --- a/docs/references/nextjs/auth.mdx +++ b/docs/references/nextjs/auth.mdx @@ -3,12 +3,20 @@ title: '`auth()`' description: Access minimal authentication data for managing sessions and data fetching. --- -The `auth()` helper returns the [`Auth`](/docs/references/backend/types/auth-object) object of the currently active user, as well as the [`redirectToSignIn()`](#redirect-to-sign-in) method. +The `auth()` helper returns the [`Auth`](/docs/references/backend/types/auth-object) object of the currently active user, as well as the [`redirectToSignIn()`](#redirect-to-sign-in) method. For machine requests, it returns the machine's auth object. - Only available for App Router. - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions. - Requires [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware) to be configured. +## `auth({ entity })` + +The `auth()` helper needs to know if it should authenticate a [session request](/docs/session-requests/overview) or a [machine request](/docs/machine-requests/overview). +By passing in the `entity` parameter, you can specify the type of request you want to authenticate. By default, it will authenticate a session request. + +> [!NOTE] +> If you want to check **both** session and machine requests, you can pass in the `entity` parameter as `'any'`. + ## `auth.protect()` `auth` includes a single property, the `protect()` method, which you can use in two ways: @@ -110,6 +118,10 @@ You can use `auth()` to check if a `userId` exists. If it's null, then there is You can use `auth()` to check if a user is authorized to access certain parts of your application or even entire routes by checking their roles or permissions. See detailed examples in the [dedicated guide](/docs/organizations/verify-user-permissions). +### Verify Machine to Machine requests + +You can use `auth()` to verify machine to machine requests by passing in the `entity` parameter as `'machine'`. To learn more, see [machine requests](/docs/machine-requests/overview). + ### Data fetching with `getToken()` -If you need to send a JWT along to a server, `getToken()` retrieves the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/making/jwt-templates). See detailed examples in the [`Auth` reference](/docs/references/backend/types/auth-object#get-token). +If you need to send a JWT along to a server, `getToken()` retrieves the current user's [session token](/docs/session-requests/session-tokens) or a [custom JWT template](/docs/session-requests/making/jwt-templates). See detailed examples in the [`Auth` reference](/docs/references/backend/types/auth-object#get-token). diff --git a/docs/references/nextjs/authjs-migration.mdx b/docs/references/nextjs/authjs-migration.mdx index b5007a64cb..6d0e02c675 100644 --- a/docs/references/nextjs/authjs-migration.mdx +++ b/docs/references/nextjs/authjs-migration.mdx @@ -230,7 +230,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. ### Use Clerk's `externalId` field - When you migrate user data from Auth.js to Clerk, Clerk generates new user IDs for each user. If you are using existing user IDs as foreign keys in your database (e.g. in a `user_id` column), you can save those IDs as the user's `externalId` in Clerk. This `externalId` can be included in the session token by adding the following [customization](/docs/backend-requests/making/custom-session-token). The following example will set the user's ID to be `externalId` if one is present, otherwise, it will use the Clerk's user ID. + When you migrate user data from Auth.js to Clerk, Clerk generates new user IDs for each user. If you are using existing user IDs as foreign keys in your database (e.g. in a `user_id` column), you can save those IDs as the user's `externalId` in Clerk. This `externalId` can be included in the session token by adding the following [customization](/docs/session-requests/making/custom-session-token). The following example will set the user's ID to be `externalId` if one is present, otherwise, it will use the Clerk's user ID. ```json { diff --git a/docs/references/nextjs/current-user.mdx b/docs/references/nextjs/current-user.mdx index c8ea1da5c5..a92120a5ce 100644 --- a/docs/references/nextjs/current-user.mdx +++ b/docs/references/nextjs/current-user.mdx @@ -9,7 +9,7 @@ Under the hood, this helper: - calls `fetch()`, so it is automatically deduped per request. - uses the [`GET /v1/users/{user_id}`](/docs/reference/backend-api/tag/Users#operation/GetUser){{ target: '_blank' }} endpoint. -- counts towards the [Backend API request rate limit](/docs/backend-requests/resources/rate-limits#rate-limits). +- counts towards the [Backend API request rate limit](/docs/rate-limits#rate-limits). ```tsx {{ filename: 'app/page.tsx' }} import { currentUser } from '@clerk/nextjs/server' diff --git a/docs/references/nextjs/read-session-data.mdx b/docs/references/nextjs/read-session-data.mdx index a1cf227541..67a3696270 100644 --- a/docs/references/nextjs/read-session-data.mdx +++ b/docs/references/nextjs/read-session-data.mdx @@ -12,7 +12,7 @@ Clerk provides a set of [hooks and helpers](/docs/references/nextjs/overview#cli [`auth()`](/docs/references/nextjs/auth) and [`currentUser()`](/docs/references/nextjs/current-user) are App Router-specific helpers that you can use inside of your Route Handlers, Middleware, Server Components, and Server Actions. - The `auth()` helper will return the [`Auth`](/docs/references/backend/types/auth-object) object of the currently active user. -- The `currentUser()` helper will return the [`Backend User`](/docs/references/backend/types/backend-user) object of the currently active user. This is helpful if you want to render information, like their first and last name, directly from the server. Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backend/overview) wrapper to make a call to the Backend API. **This does count towards the [Backend API request rate limit](/docs/backend-requests/resources/rate-limits#rate-limits)**. This also uses `fetch()` so it is automatically deduped per request. +- The `currentUser()` helper will return the [`Backend User`](/docs/references/backend/types/backend-user) object of the currently active user. This is helpful if you want to render information, like their first and last name, directly from the server. Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backend/overview) wrapper to make a call to the Backend API. **This does count towards the [Backend API request rate limit](/docs/rate-limits#rate-limits)**. This also uses `fetch()` so it is automatically deduped per request. The following example uses the [`auth()`](/docs/references/nextjs/auth) helper to validate an authenticated user and the `currentUser()` helper to access the `Backend User` object for the authenticated user. diff --git a/docs/references/sdk/backend-only.mdx b/docs/references/sdk/backend-only.mdx index c61b15e72a..4532a618ea 100644 --- a/docs/references/sdk/backend-only.mdx +++ b/docs/references/sdk/backend-only.mdx @@ -15,7 +15,7 @@ The source of truth for all BAPI endpoints is the [BAPI reference docs](/docs/re - User should be able to limit access to routes by checking for [roles and permissions](/docs/organizations/roles-permissions) > [!IMPORTANT] -> BAPI has [rate limits](/docs/backend-requests/resources/rate-limits) to help protect users against brute-force attacks or stop abuse of Clerk's platform. Be sure to include a backoff mechanism into your fetching logic and respect the `Retry-After` header to gracefully handle any active rate limits. +> BAPI has [rate limits](/docs/rate-limits) to help protect users against brute-force attacks or stop abuse of Clerk's platform. Be sure to include a backoff mechanism into your fetching logic and respect the `Retry-After` header to gracefully handle any active rate limits. If you're using `@clerk/backend` to build an SDK for an existing framework, these additional features are expected: diff --git a/docs/backend-requests/handling/go.mdx b/docs/session-requests/handling/go.mdx similarity index 100% rename from docs/backend-requests/handling/go.mdx rename to docs/session-requests/handling/go.mdx diff --git a/docs/backend-requests/handling/manual-jwt.mdx b/docs/session-requests/handling/manual-jwt.mdx similarity index 93% rename from docs/backend-requests/handling/manual-jwt.mdx rename to docs/session-requests/handling/manual-jwt.mdx index 26eb6ce46d..279c2e788e 100644 --- a/docs/backend-requests/handling/manual-jwt.mdx +++ b/docs/session-requests/handling/manual-jwt.mdx @@ -3,7 +3,7 @@ title: Manual JWT verification description: Learn how to manually verify Clerk-generated session tokens (JWTs). --- -Your Clerk-generated [session tokens](/docs/backend-requests/resources/session-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. Depending on your architecture, these tokens will be in your backend requests either via a cookie named `__session` or via the Authorization header. +Your Clerk-generated [session tokens](/docs/session-requests/session-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. Depending on your architecture, these tokens will be in your backend requests either via a cookie named `__session` or via the Authorization header. For every request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). If these validations succeed, then the user is authenticated to your application and should be considered signed in. The `authenticateRequest()` method from the JavaScript Backend SDK handles these validations for you. Alternatively, you can manually verify the token without using the SDK. See the following sections for more information. diff --git a/docs/backend-requests/handling/ruby-rails.mdx b/docs/session-requests/handling/ruby-rails.mdx similarity index 100% rename from docs/backend-requests/handling/ruby-rails.mdx rename to docs/session-requests/handling/ruby-rails.mdx diff --git a/docs/backend-requests/making/cross-origin.mdx b/docs/session-requests/making/cross-origin.mdx similarity index 93% rename from docs/backend-requests/making/cross-origin.mdx rename to docs/session-requests/making/cross-origin.mdx index 3d834bc021..e796baf48a 100644 --- a/docs/backend-requests/making/cross-origin.mdx +++ b/docs/session-requests/making/cross-origin.mdx @@ -3,7 +3,7 @@ title: Cross-origin requests description: Learn about various ways to make cross-origin requests to the backend when using Clerk SDKs. --- -If your client and server are on different origins (e.g. making an API call to a server on `api.foo.com` from JavaScript running on a client at `foo.com`), the [session token](/docs/backend-requests/resources/session-tokens) needs to be passed in a network request header. There are a few different ways this can be done on the front-end. +If your client and server are on different origins (e.g. making an API call to a server on `api.foo.com` from JavaScript running on a client at `foo.com`), the [session token](/docs/session-requests/session-tokens) needs to be passed in a network request header. There are a few different ways this can be done on the front-end. ## Using Fetch with React diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/session-requests/making/custom-session-token.mdx similarity index 97% rename from docs/backend-requests/making/custom-session-token.mdx rename to docs/session-requests/making/custom-session-token.mdx index 2dd3307cdf..fb9fbec307 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/session-requests/making/custom-session-token.mdx @@ -5,7 +5,7 @@ description: Learn how to customize the session token that is generated for you Session tokens are JWTs generated by Clerk on behalf of your instance, and convey an authenticated user session to your backend. -By default, session tokens contain claims that are required for Clerk to function. You can learn more about these "default claims" in the [session tokens](/docs/backend-requests/resources/session-tokens) documentation. +By default, session tokens contain claims that are required for Clerk to function. You can learn more about these "default claims" in the [session tokens](/docs/session-requests/session-tokens) documentation. This guide will show you how to customize a session token to include additional claims that you may need in your application. diff --git a/docs/backend-requests/making/jwt-templates.mdx b/docs/session-requests/making/jwt-templates.mdx similarity index 98% rename from docs/backend-requests/making/jwt-templates.mdx rename to docs/session-requests/making/jwt-templates.mdx index c83cc8ba3a..d0f63243b2 100644 --- a/docs/backend-requests/making/jwt-templates.mdx +++ b/docs/session-requests/making/jwt-templates.mdx @@ -4,7 +4,7 @@ description: Learn how to create custom JWT templates to generate JSON Web Token --- > [!WARNING] -> This guide is for creating custom JWT templates in order to generate JSON Web Tokens with Clerk. If you are looking for how to customize your Clerk-generated session token, refer to the [Customize your session token](/docs/backend-requests/making/custom-session-token) guide. +> This guide is for creating custom JWT templates in order to generate JSON Web Tokens with Clerk. If you are looking for how to customize your Clerk-generated session token, refer to the [Customize your session token](/docs/session-requests/making/custom-session-token) guide. Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWTs). Each JWT, or token, represents a user that is currently signed in to your application. @@ -48,7 +48,7 @@ A token generated using the template above would look something like this: ### Default claims -In every generated token, there are certain claims that are automatically included and cannot be overridden by templates. Clerk calls these "default claims" and you can learn more about them in the [Session tokens](/docs/backend-requests/resources/session-tokens) reference documentation. +In every generated token, there are certain claims that are automatically included and cannot be overridden by templates. Clerk calls these "default claims" and you can learn more about them in the [Session tokens](/docs/session-requests/session-tokens) reference documentation. ### Shortcodes diff --git a/docs/backend-requests/making/same-origin.mdx b/docs/session-requests/making/same-origin.mdx similarity index 93% rename from docs/backend-requests/making/same-origin.mdx rename to docs/session-requests/making/same-origin.mdx index 1828554f37..1fe48c935c 100644 --- a/docs/backend-requests/making/same-origin.mdx +++ b/docs/session-requests/making/same-origin.mdx @@ -3,7 +3,7 @@ title: Same-origin requests description: Learn about various ways to make same-origin requests to the backend when using Clerk SDKs. --- -If your client and server are on the same origin (e.g. making an API call to `foo.com/api` from JavaScript running on `foo.com`), the [session token](/docs/backend-requests/resources/session-tokens) is automatically passed to the backend in a cookie. This means that all requests to same-origin endpoints are authenticated by default. +If your client and server are on the same origin (e.g. making an API call to `foo.com/api` from JavaScript running on `foo.com`), the [session token](/docs/session-requests/session-tokens) is automatically passed to the backend in a cookie. This means that all requests to same-origin endpoints are authenticated by default. ## Using Fetch diff --git a/docs/backend-requests/overview.mdx b/docs/session-requests/overview.mdx similarity index 75% rename from docs/backend-requests/overview.mdx rename to docs/session-requests/overview.mdx index f083b3097c..aab9e4e371 100644 --- a/docs/backend-requests/overview.mdx +++ b/docs/session-requests/overview.mdx @@ -1,15 +1,17 @@ --- -title: Request authentication -description: Learn about various ways to make authenticated requests to the backend when using Clerk SDKs. +title: Session Requests +description: Learn about various ways to authenticate users to your backend using Clerk SDKs. --- -A request is considered “authenticated” when the backend can securely identify the user and device that is making the request. The reasons for making authenticated requests to the backend include: +Your application will likely have users sending requests to your backend. You can **authenticate** these requests by validating a [session token](/docs/session-requests/session-tokens) in the request. + +When your backend authenticates a session request, it can identify the user and device that is making the request. The reasons for making authenticated requests to the backend include: - Associating the user with the action being performed - Ensuring the user has permission to make the request - Keeping an audit log of which device the user is performing actions from -In order to authenticate the user on the backend using Clerk's SDK, the short-lived [session token](/docs/backend-requests/resources/session-tokens) needs to be passed to the server. +In order to authenticate the user on the backend using Clerk's SDK, the short-lived [session token](/docs/session-requests/session-tokens) needs to be passed to the server. ## Frontend requests @@ -21,11 +23,11 @@ The origin includes the protocol, hostname, and port (optional): ### Same-origin -For same-origin requests, refer to our guide on [making same-origin requests](/docs/backend-requests/making/same-origin). +For same-origin requests, refer to our guide on [making same-origin requests](/docs/session-requests/making/same-origin). ### Cross-origin -For cross-origin requests, refer to our guide on [making cross-origin requests](/docs/backend-requests/making/cross-origin). +For cross-origin requests, refer to our guide on [making cross-origin requests](/docs/session-requests/making/cross-origin). ## Backend requests @@ -33,8 +35,8 @@ Clerk provides various middleware packages to set the session property for easy - [Next.js](/docs/references/nextjs/clerk-middleware) - [Node.js / Express](/docs/backend-requests/handling/nodejs) -- [Go](/docs/backend-requests/handling/go) -- [Ruby on Rails / Rack](/docs/backend-requests/handling/ruby-rails) +- [Go](/docs/session-requests/handling/go) +- [Ruby on Rails / Rack](/docs/session-requests/handling/ruby-rails) If there is not middleware available for your preferred language or framework, you can extract the session token manually. @@ -46,7 +48,7 @@ For same-origin requests, the session token is included in the `__session` cooki For cross-origin requests, the Bearer token inside the `Authorization` header contains the session token. -You can read more about [manual JWT verification](/docs/backend-requests/handling/manual-jwt) for additional information. +You can read more about [manual JWT verification](/docs/session-requests/handling/manual-jwt) for additional information. ## Required headers diff --git a/docs/backend-requests/resources/session-tokens.mdx b/docs/session-requests/session-tokens.mdx similarity index 93% rename from docs/backend-requests/resources/session-tokens.mdx rename to docs/session-requests/session-tokens.mdx index ca19a995cb..17824ada2e 100644 --- a/docs/backend-requests/resources/session-tokens.mdx +++ b/docs/session-requests/session-tokens.mdx @@ -30,15 +30,15 @@ The following claims are only included if the user is part of an organization: - `org_slug`: organization slug - the slug of the currently active organization that the user belongs to. - `org_role`: organization role - the role of the user in the currently active organization. -If you would like to add custom claims to your session token, you can [customize it](/docs/backend-requests/making/custom-session-token). +If you would like to add custom claims to your session token, you can [customize it](/docs/session-requests/making/custom-session-token). -You can also create custom tokens using a [JWT template](/docs/backend-requests/making/jwt-templates). +You can also create custom tokens using a [JWT template](/docs/session-requests/making/jwt-templates). ## Size limitations The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. -A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/making/custom-session-token). In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. +A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/session-requests/making/custom-session-token). In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. Claims to monitor for size limits: @@ -51,10 +51,10 @@ Claims to monitor for size limits: If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit. > [!NOTE] -> If your application encounters this issue, the Clerk Dashboard will display a warning: **"Some users are exceeding cookie size limits"**. To resolve this, update your [custom session token](/docs/backend-requests/making/custom-session-token). +> If your application encounters this issue, the Clerk Dashboard will display a warning: **"Some users are exceeding cookie size limits"**. To resolve this, update your [custom session token](/docs/session-requests/making/custom-session-token). ## Validate session tokens If you're using the middleware provided by our Clerk SDKs, this is all handled automatically in every request. If you're not using the middleware, you can still use the respective helpers provided by the SDKs to validate the tokens. -To learn how to manually verify a session token, refer to the [dedicated guide](/docs/backend-requests/handling/manual-jwt). +To learn how to manually verify a session token, refer to the [dedicated guide](/docs/session-requests/handling/manual-jwt). diff --git a/docs/testing/postman-or-insomnia.mdx b/docs/testing/postman-or-insomnia.mdx index 8ac7c8e64a..6c7d562725 100644 --- a/docs/testing/postman-or-insomnia.mdx +++ b/docs/testing/postman-or-insomnia.mdx @@ -9,7 +9,7 @@ Postman and Insomnia are powerful tools used to test API's, validate their behav The standard token issued by Clerk expires after 60 seconds. Clerk SDKs handle refreshing the token regularly so that the authentication state is kept up to date. Because this token expires quickly, it isn't very useful when trying to test with Postman or Insomnia. -You will want to create a long-lived [JWT Template](/docs/backend-requests/making/jwt-templates) to be used in Postman or Insomnia. To do so, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Select **New template** then choose the **Blank** template. +You will want to create a long-lived [JWT Template](/docs/session-requests/making/jwt-templates) to be used in Postman or Insomnia. To do so, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Select **New template** then choose the **Blank** template. ![The JWT templates page in the Clerk Dashboard. The 'New template' button was clicked, in the modal that opened, the 'Blank' template is hovered over](/docs/images/testing/blank-jwt-template.webp) diff --git a/docs/upgrade-guides/core-2/backend.mdx b/docs/upgrade-guides/core-2/backend.mdx index 77db6c5656..f41623db1b 100644 --- a/docs/upgrade-guides/core-2/backend.mdx +++ b/docs/upgrade-guides/core-2/backend.mdx @@ -254,7 +254,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Changes to pagination arguments for some functions diff --git a/docs/upgrade-guides/core-2/chrome-extension.mdx b/docs/upgrade-guides/core-2/chrome-extension.mdx index 4dca7c450a..1dbc853998 100644 --- a/docs/upgrade-guides/core-2/chrome-extension.mdx +++ b/docs/upgrade-guides/core-2/chrome-extension.mdx @@ -168,7 +168,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/upgrade-guides/core-2/expo.mdx b/docs/upgrade-guides/core-2/expo.mdx index 1a0b6f4d7c..602b384690 100644 --- a/docs/upgrade-guides/core-2/expo.mdx +++ b/docs/upgrade-guides/core-2/expo.mdx @@ -148,7 +148,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/upgrade-guides/core-2/fastify.mdx b/docs/upgrade-guides/core-2/fastify.mdx index 1bd1c8edf5..5545865fd1 100644 --- a/docs/upgrade-guides/core-2/fastify.mdx +++ b/docs/upgrade-guides/core-2/fastify.mdx @@ -109,7 +109,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Image URL Name Consolidation diff --git a/docs/upgrade-guides/core-2/javascript.mdx b/docs/upgrade-guides/core-2/javascript.mdx index 5becd27bb6..ca77300b8d 100644 --- a/docs/upgrade-guides/core-2/javascript.mdx +++ b/docs/upgrade-guides/core-2/javascript.mdx @@ -157,7 +157,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/upgrade-guides/core-2/nextjs.mdx b/docs/upgrade-guides/core-2/nextjs.mdx index 936279a981..6bfc979814 100644 --- a/docs/upgrade-guides/core-2/nextjs.mdx +++ b/docs/upgrade-guides/core-2/nextjs.mdx @@ -544,7 +544,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/upgrade-guides/core-2/node.mdx b/docs/upgrade-guides/core-2/node.mdx index f69ec9ae4e..b0dedce505 100644 --- a/docs/upgrade-guides/core-2/node.mdx +++ b/docs/upgrade-guides/core-2/node.mdx @@ -154,7 +154,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Image URL Name Consolidation diff --git a/docs/upgrade-guides/core-2/react.mdx b/docs/upgrade-guides/core-2/react.mdx index 7e07ddc715..70e12703c5 100644 --- a/docs/upgrade-guides/core-2/react.mdx +++ b/docs/upgrade-guides/core-2/react.mdx @@ -185,7 +185,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/upgrade-guides/core-2/remix.mdx b/docs/upgrade-guides/core-2/remix.mdx index 26484d9663..9e6aab9f24 100644 --- a/docs/upgrade-guides/core-2/remix.mdx +++ b/docs/upgrade-guides/core-2/remix.mdx @@ -191,7 +191,7 @@ The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where -If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. +If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/session-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it. ### Path routing is now the default diff --git a/docs/users/metadata.mdx b/docs/users/metadata.mdx index 2f49bacac7..382ce7e34a 100644 --- a/docs/users/metadata.mdx +++ b/docs/users/metadata.mdx @@ -268,7 +268,7 @@ There are multiple ways to retrieve public metadata. On the frontend, it's available on the [`User`](/docs/references/javascript/user/user) object which can be accessed using the [`useUser()`](/docs/references/react/use-user) hook. -On the backend, it's available on the [Backend `User`](/docs/references/backend/types/backend-user) object which can be accessed using the JavaScript Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method. It can also be attached to a session token, and the `sessionClaims` of the session token can be retrieved on the [`Auth`](/docs/references/backend/types/auth-object) object. If you need to retrieve public metadata frequently in the backend, the best option is to attach it to the session token and retrieve it from the session token. See the [guide on customizing your session token](/docs/backend-requests/making/custom-session-token). +On the backend, it's available on the [Backend `User`](/docs/references/backend/types/backend-user) object which can be accessed using the JavaScript Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method. It can also be attached to a session token, and the `sessionClaims` of the session token can be retrieved on the [`Auth`](/docs/references/backend/types/auth-object) object. If you need to retrieve public metadata frequently in the backend, the best option is to attach it to the session token and retrieve it from the session token. See the [guide on customizing your session token](/docs/session-requests/making/custom-session-token). ## Unsafe metadata @@ -496,4 +496,4 @@ There are multiple ways to retrieve unsafe metadata. On the frontend, it is available on the [`User`](/docs/references/javascript/user/user) object, which you can access by using the [`useUser()`](/docs/references/react/use-user) hook. -On the backend, it's available on the [Backend `User`](/docs/references/backend/types/backend-user) object which can be accessed using the JavaScript Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method. It can also be attached to a session token, and the `sessionClaims` of the session token can be retrieved on the [`Auth`](/docs/references/backend/types/auth-object) object. If you need to retrieve unsafe metadata frequently in the backend, the best option is to attach it to the session token and retrieve it from the session token. See the [guide on customizing your session token](/docs/backend-requests/making/custom-session-token). +On the backend, it's available on the [Backend `User`](/docs/references/backend/types/backend-user) object which can be accessed using the JavaScript Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method. It can also be attached to a session token, and the `sessionClaims` of the session token can be retrieved on the [`Auth`](/docs/references/backend/types/auth-object) object. If you need to retrieve unsafe metadata frequently in the backend, the best option is to attach it to the session token and retrieve it from the session token. See the [guide on customizing your session token](/docs/session-requests/making/custom-session-token). diff --git a/docs/users/user-impersonation.mdx b/docs/users/user-impersonation.mdx index 69f35b3b64..01ea72d726 100644 --- a/docs/users/user-impersonation.mdx +++ b/docs/users/user-impersonation.mdx @@ -68,7 +68,7 @@ The [Frontend API](/docs/reference/frontend-api/){{ target: '_blank' }} will red Once a user is signed in as a different user, Clerk provides APIs and helper methods to distinguish an impersonated session from a regular session. -Clerk also adds an `act` claim on the [Clerk session token](/docs/backend-requests/resources/session-tokens), which contains information like the impersonated session ID and the actor/impersonator's user ID. +Clerk also adds an `act` claim on the [Clerk session token](/docs/session-requests/session-tokens), which contains information like the impersonated session ID and the actor/impersonator's user ID. > [!NOTE] > When using a custom JWT template, the `{{session.actor}}` will need to be added as a claim in order to expose it. diff --git a/docs/backend-requests/versioning/available-versions.mdx b/docs/versioning/available-versions.mdx similarity index 100% rename from docs/backend-requests/versioning/available-versions.mdx rename to docs/versioning/available-versions.mdx diff --git a/docs/backend-requests/versioning/overview.mdx b/docs/versioning/overview.mdx similarity index 95% rename from docs/backend-requests/versioning/overview.mdx rename to docs/versioning/overview.mdx index fa332268a2..1d4ac8e90c 100644 --- a/docs/backend-requests/versioning/overview.mdx +++ b/docs/versioning/overview.mdx @@ -5,7 +5,7 @@ description: A brief guide on how versioning works in Clerk. When backwards incompatible changes are necessary for an API, new versions are released to prevent disruption to existing applications. These versions are identified by their release date, such as 2021-02-05. Both the frontend and backend APIs follow the same version. -A complete list of all the available versions with their changes can be found on the [API versions](/docs/backend-requests/versioning/available-versions) page. +A complete list of all the available versions with their changes can be found on the [API versions](/docs/versioning/available-versions) page. ## What constitutes a breaking change