Skip to content

Commit 9d97c4d

Browse files
alex-ntousiasalex-ntousias
authored
Re-publish JWT v2 docs (#2185)
1 parent 39c71cc commit 9d97c4d

File tree

4 files changed

+101
-31
lines changed

4 files changed

+101
-31
lines changed

‎docs/backend-requests/resources/session-tokens.mdx

+78-29
Original file line numberDiff line numberDiff line change
@@ -9,35 +9,84 @@ Read more about Clerk session tokens and how they work in [the dedicated blog po
99

1010
## Default claims
1111

12-
Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
13-
14-
| Claim | Abbreviation expanded | Description | Example |
15-
| - | - | - | - |
16-
| `azp` | authorized party | The `Origin` header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. This claim could be omitted if, for privacy-related reasons, `Origin` is empty or null. | `https://example.com` |
17-
| `exp` | expiration time | The time after which the token will expire, as a Unix timestamp. Determined using the **Token lifetime** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information. | `1713158400` |
18-
| `fva` | factor verification age | Each item represents the minutes that have passed since the last time a first or second factor, respectively, was verified. | `[7, -1]` which means it has been 7 minutes since the first factor was verified, and there either is not a second factor or the second factor has never been verified. |
19-
| `iat` | issued at | The time at which the token was issued as a Unix timestamp. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information. | `1713158400` |
20-
| `iss` | issuer | The Frontend API URL of your instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information. | `https://clerk.your-site.com` for a production instance, `https://your-site.clerk.accounts.dev` for a development instance |
21-
| `nbf` | not before | The time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information. | `1713158400` |
22-
| `sid` | session ID | The ID of the current session. | `sess_123` |
23-
| `sub` | subject | The ID of the current user of the session. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. | `user_123` |
24-
25-
The **`act` (actor) claim** is only included if the user is [impersonating](/docs/users/user-impersonation) another user. It's value is an object that contains the following properties:
26-
27-
| Claim | Abbreviation expanded | Description | Example |
28-
| - | - | - | - |
29-
| `iss` | issuer | The referrer of the token. | `https://dashboard.clerk.com` |
30-
| `sid` | session ID | The session ID of the impersonated session. | `sess_456` |
31-
| `sub` | subject | The ID of the impersonator. | `user_456` |
32-
33-
The following claims are only included if the user is part of an [organization](/docs/organizations/overview):
34-
35-
| Claim | Abbreviation expanded | Description | Example |
36-
| - | - | - | - |
37-
| `org_id` | organization ID | The ID of the active organization that the user belongs to. | `org_123` |
38-
| `org_permissions` | organization permissions | The permissions of the user in the currently active organization. System permissions are not included in the session token. | `["org:admin:example_permission", "org:member:example_permission"]` |
39-
| `org_slug` | organization slug | The slug of the currently active organization that the user belongs to. | `org-slug` |
40-
| `org_role` | organization role | The role of the user in the currently active organization. | `org:admin` |
12+
<Tabs items={["Version 2", "Version 1"]}>
13+
<Tab>
14+
> [!IMPORTANT]
15+
> You are reading about version 2 of Clerk's session token claims. To read about version 1, select the respective tab above.
16+
17+
Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
18+
19+
| Claim | Abbreviation expanded | Description | Example |
20+
| - | - | - | - |
21+
| `azp` | authorized party | The `Origin` header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. This claim could be omitted if, for privacy-related reasons, `Origin` is empty or null. | `https://example.com` |
22+
| `exp` | expiration time | The time after which the token will expire, as a Unix timestamp. Determined using the **Token lifetime** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information. | `1713158400` |
23+
| `fva` | factor verification age | Each item represents the minutes that have passed since the last time a first or second factor, respectively, was verified. | `[7, -1]` which means it has been 7 minutes since the first factor was verified, and there either is not a second factor or the second factor has never been verified. |
24+
| `iat` | issued at | The time at which the token was issued as a Unix timestamp. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information. | `1713158400` |
25+
| `iss` | issuer | The Frontend API URL of your instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information. | `https://clerk.your-site.com` for a production instance, `https://your-site.clerk.accounts.dev` for a development instance |
26+
| `nbf` | not before | The time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information. | `1713158400` |
27+
| `sid` | session ID | The ID of the current session. | `sess_123` |
28+
| `sub` | subject | The ID of the current user of the session. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. | `user_123` |
29+
| `v` | version | The version number of the session token. | `2` |
30+
| `fea` | features | A list of enabled features and their scope. The scope can either be `o` for org-level features, `u` for user-level features, or `uo` for both. | `o:dashboard,o:impersonation` |
31+
32+
The **`o` claim**, or organization claim, is only included if the user is part of an [organization](/docs/organizations/overview) and that organization is [active](/docs/organizations/overview#active-organization). Its value is an object that contains the following properties:
33+
34+
| Claim | Abbreviation expanded | Description | Example |
35+
| - | - | - | - |
36+
| `id` | ID | The ID of the organization. | `org_123` |
37+
| `slg` | slug | The slug of the organization. | `org-slug` |
38+
| `rol` | role | The role of the user in the organization, without the `org:` prefix. | `admin` |
39+
| `per` | permissions | The names of the permissions the user has in the organization. | `read,manage` |
40+
| `fpm` | feature-permission map | The mapping of features with permissions, where the value of the integer, when converted to binary, represents a bitmask where each bit's position corresponds to a permission in the `o.per` list, and where `0` = `not-allowed` and `1` = `allowed`. | `3,2` |
41+
42+
> [!WARNING]
43+
> The organization claims above are intentionally designed to be as compact as possible to keep JWT tokens small.
44+
> As a result, they can be difficult to decode manually. We strongly recommend using one of our SDKs that support API version [2025-04-10](/docs/versioning/available-versions#2025-04-10) to handle decoding reliably.
45+
46+
The **`act` (actor) claim** is only included if the user is [impersonating](/docs/users/user-impersonation) another user. It's value is an object that contains the following properties:
47+
48+
| Claim | Abbreviation expanded | Description | Example |
49+
| - | - | - | - |
50+
| `iss` | issuer | The referrer of the token. | `https://dashboard.clerk.com` |
51+
| `sid` | session ID | The session ID of the impersonated session. | `sess_456` |
52+
| `sub` | subject | The ID of the impersonator. | `user_456` |
53+
</Tab>
54+
55+
<Tab>
56+
> [!IMPORTANT]
57+
> Version 1 was deprecated on April 14, 2025. To upgrade to version 2, go to the [**Updates**](https://dashboard.clerk.com/last-active?path=updates) page in the Clerk Dashboard.
58+
59+
Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include:
60+
61+
| Claim | Abbreviation expanded | Description | Example |
62+
| - | - | - | - |
63+
| `azp` | authorized party | The `Origin` header that was included in the original Frontend API request made from the user. Most commonly, it will be the URL of the application. This claim could be omitted if, for privacy-related reasons, `Origin` is empty or null. | `https://example.com` |
64+
| `exp` | expiration time | The time after which the token will expire, as a Unix timestamp. Determined using the **Token lifetime** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) for more information. | `1713158400` |
65+
| `fva` | factor verification age | Each item represents the minutes that have passed since the last time a first or second factor, respectively, was verified. | `[7, -1]` which means it has been 7 minutes since the first factor was verified, and there either is not a second factor or the second factor has never been verified. |
66+
| `iat` | issued at | The time at which the token was issued as a Unix timestamp. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) for more information. | `1713158400` |
67+
| `iss` | issuer | The Frontend API URL of your instance. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) for more information. | `https://clerk.your-site.com` for a production instance, `https://your-site.clerk.accounts.dev` for a development instance |
68+
| `nbf` | not before | The time before which the token is considered invalid, as a Unix timestamp. Determined using the **Allowed Clock Skew** JWT template setting in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) for more information. | `1713158400` |
69+
| `sid` | session ID | The ID of the current session. | `sess_123` |
70+
| `sub` | subject | The ID of the current user of the session. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. | `user_123` |
71+
72+
The following claims are only included if the user is part of an organization and that organization is [active](/docs/organizations/overview#active-organization):
73+
74+
| Claim | Abbreviation expanded | Description | Example |
75+
| - | - | - | - |
76+
| `org_id` | organization ID | The ID of the active organization that the user belongs to. | `org_123` |
77+
| `org_permissions` | organization permissions | The permissions of the user in the currently active organization. System permissions are not included in the session token. | `["org:admin:example_permission", "org:member:example_permission"]` |
78+
| `org_slug` | organization slug | The slug of the currently active organization that the user belongs to. | `org-slug` |
79+
| `org_role` | organization role | The role of the user in the currently active organization. | `org:admin` |
80+
81+
The **`act` (actor) claim** is only included if the user is [impersonating](/docs/users/user-impersonation) another user. It's value is an object that contains the following properties:
82+
83+
| Claim | Abbreviation expanded | Description | Example |
84+
| - | - | - | - |
85+
| `iss` | issuer | The referrer of the token. | `https://dashboard.clerk.com` |
86+
| `sid` | session ID | The session ID of the impersonated session. | `sess_456` |
87+
| `sub` | subject | The ID of the impersonator. | `user_456` |
88+
</Tab>
89+
</Tabs>
4190

4291
If you would like to add custom claims to your session token, you can [customize it](/docs/backend-requests/custom-session-token).
4392

‎docs/organizations/create-roles-permissions.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ In the Clerk Dashboard, you can create roles, assign permissions to them, and ch
1616

1717
1. In the Clerk Dashboard, navigate to [**Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/permissions).
1818
1. Select **Create new permission**.
19-
1. Give the permission a name, a key to reference it by in the format `org:<resource>:<action>`, and a description.
19+
1. Give the permission a name, a key to reference it by in the format `org:<feature>:<action>`, and a description.
2020
1. Select **Create permission**.
2121

2222
## Change a user's role in an organization

‎docs/organizations/roles-permissions.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ You can assign these system permissions to any role.
6565
6666
### Custom permissions
6767

68-
When creating a new permission, follow the format `org:<resource>:<action>`. You can then assign the permission to an existing role.
68+
When creating a new permission, follow the format `org:<feature>:<action>`. You can then assign the permission to an existing role.
6969

7070
For example, you could create a new role called **Sales** (`org:sales`) and a new permission called **Create invoices** (`org:invoices:create`) which allows only users with this permission to edit invoices. You could also grant this permission to the **Billing** role.
7171

‎docs/versioning/available-versions.mdx

+21
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,27 @@ description: A list of the available API versions and their breaking changes.
55

66
Below is a list of all the available API versions with their respective breaking changes. For information on how to apply the appropriate version, see [Versioning overview](/docs/versioning/overview).
77

8+
### 2025-04-10
9+
10+
Adds support for [version 2 of Clerk session tokens](/docs/backend-requests/resources/session-tokens).
11+
The following SDKs are compatible with this version:
12+
13+
| SDK | Version |
14+
| - | - |
15+
| Clerk.js | @clerk/clerk-js v5.61.0 or higher |
16+
| Next.js | @clerk/nextjs v6.15.0 or higher |
17+
| Astro | @clerk/astro v2.6.4 or higher |
18+
| Expo | @clerk/expo v2.9.12 or higher |
19+
| Express | @clerk/express v1.4.5 or higher |
20+
| Fastify | @clerk/fastify v2.2.5 or higher |
21+
| Go | clerk-sdk-go v2.3.1 or higher |
22+
| JavaScript Backend | @clerk/backend v1.28.0 or higher |
23+
| Nuxt.js | @clerk/nuxt v1.5.5 or higher |
24+
| React Router | @clerk/react-router v1.2.5 or higher |
25+
| Remix | @clerk/remix v4.5.17 or higher |
26+
| Ruby | clerk-sdk-ruby v4.1.0 or higher |
27+
| TanStack React Start | @clerk/tanstack-react-start v0.13.5 or higher |
28+
829
### 2024-10-01
930

1031
- Notification for new sign-ins to users' accounts feature becomes available.

0 commit comments

Comments
 (0)