Skip to content

Commit

Permalink
Remove /cookie-size-limits page; move info to /session-tokens (#1751)
Browse files Browse the repository at this point in the history
Co-authored-by: victoria <[email protected]>
  • Loading branch information
alexisintech and victoriaxyz authored Nov 27, 2024
1 parent 5b19f54 commit 9d14007
Show file tree
Hide file tree
Showing 6 changed files with 21 additions and 19 deletions.
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
> [!CAUTION]
> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
> It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend.
> [Learn more](/docs/backend-requests/resources/cookie-size-limits).
> [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).
2 changes: 1 addition & 1 deletion docs/backend-requests/making/custom-session-token.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ By default, session tokens contain claims that are required for Clerk to functio

This guide will show you how to customize a session token to include additional claims that you may need in your application.

<Include src="_partials/cookie-size-callout" />
<Include src="_partials/token-size-callout" />

{/* TODO: Update the H3 to an H2 when the Steps component can accept headings other than H3. */}

Expand Down
2 changes: 1 addition & 1 deletion docs/backend-requests/making/jwt-templates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/

You can control the claims that will go into these tokens by creating custom **JWT Templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format.

<Include src="_partials/cookie-size-callout" />
<Include src="_partials/token-size-callout" />

## What is a JWT template?

Expand Down
12 changes: 0 additions & 12 deletions docs/backend-requests/resources/cookie-size-limits.mdx

This file was deleted.

18 changes: 18 additions & 0 deletions docs/backend-requests/resources/session-tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ description: Learn about session tokens and how to validate them in your backend

When a user is authenticated in your application, Clerk generates a short-lived session token that you can use to authenticate requests to your backend. This token is a JSON Web Token (JWT) that contains information about the user and their session.

Learn more about how Clerk combines session token authentication and JWT authentication in the [blog post](https://clerk.com/blog/combining-the-benefits-of-session-tokens-and-jwts).

## Default session claims

Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
Expand Down Expand Up @@ -32,6 +34,22 @@ If you would like to add custom claims to your session token, you can [customize

You can also create custom tokens using a [JWT template](/docs/backend-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) or creating a [custom JWT template](/docs/backend-requests/making/jwt-templates). In these cases, 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:

- `user.organizations`
- `user.public_metadata`
- `user.unsafe_metadata`
- `org.public_metadata`
- `org_membership.public_metadata`

If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit.

## 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.
Expand Down
4 changes: 0 additions & 4 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -822,10 +822,6 @@
"title": "Session tokens",
"href": "/docs/backend-requests/resources/session-tokens"
},
{
"title": "Cookie size limits",
"href": "/docs/backend-requests/resources/cookie-size-limits"
},
{
"title": "Rate limits",
"href": "/docs/backend-requests/resources/rate-limits"
Expand Down

0 comments on commit 9d14007

Please sign in to comment.