diff --git a/docs/_partials/has-warning.mdx b/docs/_partials/has-warning.mdx
new file mode 100644
index 0000000000..40f9dda9f1
--- /dev/null
+++ b/docs/_partials/has-warning.mdx
@@ -0,0 +1,2 @@
+> [!WARNING]
+> When using `has()` **on the server-side** to check permissions, it only works with **custom permissions**, as [system permissions](/docs/organizations/roles-permissions#system-permissions) are not included in `auth.sessionClaims.orgs_permissions`. To check system permissions, verify the user's role instead.
diff --git a/docs/_partials/reverification-route-handler.mdx b/docs/_partials/nextjs/reverification-route-handler.mdx
similarity index 64%
rename from docs/_partials/reverification-route-handler.mdx
rename to docs/_partials/nextjs/reverification-route-handler.mdx
index acdc4f0248..e258475a53 100644
--- a/docs/_partials/reverification-route-handler.mdx
+++ b/docs/_partials/nextjs/reverification-route-handler.mdx
@@ -1,4 +1,4 @@
-The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationErrorResponse` utility is used to return an error.
+The following example uses the [`has()`](/docs/references/backend/types/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationErrorResponse` utility is used to return an error.
```tsx {{ filename: 'app/api/reverification-example/route.ts' }}
import { auth, reverificationErrorResponse } from '@clerk/nextjs/server'
diff --git a/docs/backend-requests/handling/js-backend-sdks.mdx b/docs/backend-requests/handling/js-backend-sdks.mdx
index 587430f4cf..4dee29e62b 100644
--- a/docs/backend-requests/handling/js-backend-sdks.mdx
+++ b/docs/backend-requests/handling/js-backend-sdks.mdx
@@ -7,7 +7,7 @@ To handle authenticated requests, use one of the following JS Backend SDKs.
## Clerk Express SDK
-The `clerkMiddleware()` function checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkMiddleware()` function attaches the [properties](/docs/references/nextjs/auth-object#auth-object-properties) of the authenticated user to the request object.
+The `clerkMiddleware()` function checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkMiddleware()` function attaches the [properties](/docs/references/backend/types/auth-object#auth-object-properties) of the authenticated user to the request object.
```js
import { clerkMiddleware } from '@clerk/express'
@@ -25,7 +25,7 @@ For more information on the Middleware functions and SDK features, see the [Expr
## Clerk Fastify SDK
-The `clerkPlugin` checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkPlugin` attaches the [properties](/docs/references/nextjs/auth-object#auth-object-properties) of the authenticated user to the request object.
+The `clerkPlugin` checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkPlugin` attaches the [properties](/docs/references/backend/types/auth-object#auth-object-properties) of the authenticated user to the request object.
```ts
import 'dotenv/config'
diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx
index f0f65d21ba..999b5283b0 100644
--- a/docs/backend-requests/making/custom-session-token.mdx
+++ b/docs/backend-requests/making/custom-session-token.mdx
@@ -24,7 +24,7 @@ This guide will show you how to customize a session token to include additional
## Use the custom claims in your application
- The [`Auth`](/docs/references/nextjs/auth-object) object includes a `sessionClaims` property that contains the custom claims you added to your session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts.
+ The [`Auth`](/docs/references/backend/types/auth-object) object includes a `sessionClaims` property that contains the custom claims you added to your session token. It's returned by the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts.
The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step. This examples are written for Next.js, but they can be adapted to other frameworks by using the appropriate method for accessing the `Auth` object.
diff --git a/docs/backend-requests/making/jwt-templates.mdx b/docs/backend-requests/making/jwt-templates.mdx
index 96d42f6339..c83cc8ba3a 100644
--- a/docs/backend-requests/making/jwt-templates.mdx
+++ b/docs/backend-requests/making/jwt-templates.mdx
@@ -171,7 +171,7 @@ To create a JWT template:
## Generate a JWT
-To generate a token using a template, you can use the `getToken()` method. See the [reference documentation](/docs/references/nextjs/auth-object#get-token) for more information and example usage.
+To generate a token using a template, you can use the `getToken()` method. See the [reference documentation](/docs/references/backend/types/auth-object#get-token) for more information and example usage.
## Complete example
diff --git a/docs/customization/user-button.mdx b/docs/customization/user-button.mdx
index 943248d0f3..620edfa042 100644
--- a/docs/customization/user-button.mdx
+++ b/docs/customization/user-button.mdx
@@ -457,7 +457,7 @@ With the above example, the `` menu items will be in the following
## Conditionally render menu items
-To conditionally render menu items based on a user's role or permissions, you can use the [`has()`](/docs/references/nextjs/auth-object#has) helper function:
+To conditionally render menu items based on a user's role or custom permissions, you can use the [`has()`](/docs/references/backend/types/auth-object#has) helper function:
diff --git a/docs/guides/force-organizations.mdx b/docs/guides/force-organizations.mdx
index b3ca2eac15..1b319d88fa 100644
--- a/docs/guides/force-organizations.mdx
+++ b/docs/guides/force-organizations.mdx
@@ -72,7 +72,7 @@ This guide will be written for Next.js applications using App Router, but the sa
### Detect an active organization
- A session will always include an `orgId` via the [`Auth` object](/docs/references/nextjs/auth-object#auth-object-example-with-active-organization). This can be used to detect if a user has an active organization.
+ A session will always include an `orgId` via the [`Auth` object](/docs/references/backend/types/auth-object#auth-object-example-with-active-organization). This can be used to detect if a user has an active organization.
diff --git a/docs/guides/reverification.mdx b/docs/guides/reverification.mdx
index c4d1fdac9e..ee5819b034 100644
--- a/docs/guides/reverification.mdx
+++ b/docs/guides/reverification.mdx
@@ -16,11 +16,11 @@ To implement reverification, you need to handle it both on the server- and clien
### Handle reverification server-side
-To handle reverification server-side, use the [`auth.has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. Pass a [configuration](#supported-verification-configurations) to set the time period you would like. If the user hasn't verified their credentials within that time period, return either `reverificationError` or `reverificationErrorResponse`, depending on the framework you're using. Use the following tabs to see examples for different frameworks.
+To handle reverification server-side, use the [`auth.has()`](/docs/references/backend/types/auth-object#has) helper to check if the user has verified their credentials within a specific time period. Pass a [configuration](#supported-verification-configurations) to set the time period you would like. If the user hasn't verified their credentials within that time period, return either `reverificationError` or `reverificationErrorResponse`, depending on the framework you're using. Use the following tabs to see examples for different frameworks.
- The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationError` utility is used to return an error.
+ The following example uses the [`has()`](/docs/references/backend/types/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationError` utility is used to return an error.
```ts {{ filename: 'app/actions.ts' }}
'use server'
@@ -45,7 +45,7 @@ To handle reverification server-side, use the [`auth.has()`](/docs/references/ne
-
+
@@ -189,7 +189,7 @@ The following example demonstrates how to use the [`useReverification()`](/docs/
## Supported reverification configurations
-To define the time period of the reverification check, you can pass the one of the following configurations to the `has()` helper: `strict_mfa`, `strict`, `moderate`, and `lax`. See the [`has()` reference doc](/docs/references/nextjs/auth-object#check-authorization-params-with-custom-permissions) for more details.
+To define the time period of the reverification check, you can pass the one of the following configurations to the `has()` helper: `strict_mfa`, `strict`, `moderate`, and `lax`. See the [`has()` reference doc](/docs/references/backend/types/auth-object#check-authorization-params-with-custom-permissions) for more details.
## Caveats
diff --git a/docs/manifest.json b/docs/manifest.json
index 42d48006ec..e740b3cd99 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1828,10 +1828,6 @@
"title": "`clerkMiddleware()`",
"wrap": false,
"href": "/docs/references/nextjs/clerk-middleware"
- },
- {
- "title": "Auth Object",
- "href": "/docs/references/nextjs/auth-object"
}
]
]
@@ -3182,8 +3178,8 @@
"items": [
[
{
- "title": "`PaginatedResourceResponse`",
- "href": "/docs/references/backend/types/paginated-resource-response"
+ "title": "`Auth` object",
+ "href": "/docs/references/backend/types/auth-object"
},
{
"title": "Backend `AllowlistIdentifier` object",
@@ -3220,6 +3216,10 @@
{
"title": "Backend `User` object",
"href": "/docs/references/backend/types/backend-user"
+ },
+ {
+ "title": "`PaginatedResourceResponse`",
+ "href": "/docs/references/backend/types/paginated-resource-response"
}
]
]
diff --git a/docs/organizations/org-slugs-in-urls.mdx b/docs/organizations/org-slugs-in-urls.mdx
index b9fc090ff9..fefae307f5 100644
--- a/docs/organizations/org-slugs-in-urls.mdx
+++ b/docs/organizations/org-slugs-in-urls.mdx
@@ -227,7 +227,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/nextjs/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 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:
@@ -241,7 +241,7 @@ This guide shows you how to add organization slugs to your app's URLs, configure
```
1. Select **Save**.
- You can now access the [`sessionClaims`](/docs/references/nextjs/auth-object#:~:text=sessionClaims)
+ Then, access the [`sessionClaims`](/docs/references/backend/types/auth-object#:~:text=sessionClaims)
on the `Auth` object.
```tsx {{ filename: 'app/orgs/[slug]/page.tsx', mark: [[23, 24]] }}
diff --git a/docs/organizations/roles-permissions.mdx b/docs/organizations/roles-permissions.mdx
index e5174ad494..8d2355b251 100644
--- a/docs/organizations/roles-permissions.mdx
+++ b/docs/organizations/roles-permissions.mdx
@@ -45,11 +45,11 @@ When a user creates a new organization, that user is automatically added as the
Permissions grant users privileged access to resources and operations, like creating and deleting. Clerk supports two types of permissions: System and Custom.
-### System Permissions
+### System permissions
-Clerk has a set of System Permissions that power [Clerk’s Frontend API](/docs/reference/frontend-api){{ target: '_blank' }} and [organization-related Clerk components](/docs/components/overview#organization-components). They are a baseline set of permissions that Clerk needs to operate functionally.
+Clerk has a set of system permissions that power [Clerk's Frontend API](/docs/reference/frontend-api){{ target: '_blank' }} and [organization-related Clerk components](/docs/components/overview#organization-components). They are a baseline set of permissions that Clerk needs to operate functionally.
-Clerk’s System Permissions consist of the following:
+Clerk's system permissions consist of the following:
- Manage Organization (`org:sys_profile:manage`)
- Delete Organization (`org:sys_profile:delete`)
@@ -58,10 +58,10 @@ Clerk’s System Permissions consist of the following:
- Read domains (`org:sys_domains:read`)
- Manage domains (`org:sys_domains:manage`)
-You can assign these System Permissions to any role.
+You can assign these system permissions to any role.
> [!WARNING]
-> System permissions are not included in session claims. To do permission-checks on the server-side, you must [create custom permissions](/docs/organizations/create-roles-permissions).
+> System permissions are not included in [session claims](/docs/backend-requests/resources/session-tokens#default-session-claims). To do permission-checks on the server-side, you must [create custom permissions](/docs/organizations/create-roles-permissions).
### Custom permissions
diff --git a/docs/organizations/verified-domains.mdx b/docs/organizations/verified-domains.mdx
index bc45a9d06d..9dfac6a625 100644
--- a/docs/organizations/verified-domains.mdx
+++ b/docs/organizations/verified-domains.mdx
@@ -33,7 +33,7 @@ Once a domain is added and verified in your organization, the user will have the
## Adding and verifying domains
-Domains can be added and verified under an organization by any user with the `org:sys_domains:manage` permission. By default, admins have this permission. The easiest way to add and verify domains is by using Clerk's \[``] component. In the **General** tab, there will be a **Verified domains** section.
+Domains can be added and verified under an organization by any user with the `org:sys_domains:manage` permission. By default, admins have this permission. The easiest way to add and verify domains is by using Clerk's [``](/docs/components/organization/organization-switcher) component. In the **General** tab, there will be a **Verified domains** section.
Domains can be verified through an email verification code sent to an email that matches the domain. If the user adding the domain already has a verified email using that domain in their account, the domain will be automatically verified.
diff --git a/docs/organizations/verify-user-permissions.mdx b/docs/organizations/verify-user-permissions.mdx
index b46651b529..58241c1453 100644
--- a/docs/organizations/verify-user-permissions.mdx
+++ b/docs/organizations/verify-user-permissions.mdx
@@ -14,7 +14,7 @@ Clerk enables two broad approaches to role and permissions-based authorization:
- Use the [``](/docs/components/protect) component to prevent content from rendering if the active user is unauthorized.
- Call [`auth.protect()`](/docs/references/nextjs/auth#protect) to throw a `404` error if the active user is unauthorized.
1. If you would like more control over the response when a user is unauthorized, you can:
- - Call the [`has()`](/docs/references/nextjs/auth-object#has) helper, which returns `false` if the active user lacks the role or permissions you're checking for. You can _choose_ how your app responds instead of immediately preventing content from rendering or throwing an error.
+ - Call the [`has()`](/docs/references/backend/types/auth-object#has) helper, which returns `false` if the active user lacks the role or permissions you're checking for. You can _choose_ how your app responds instead of immediately preventing content from rendering or throwing an error.
## Authorization in Client Components
@@ -261,7 +261,7 @@ The following examples work for both SSR and CSR.
## Authorization in Remix Loaders
-The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has the correct permission. If the user is not authorized, `has()` will return false, causing the loader to redirect the user to the `/request-access` route.
+The following example uses the [`has()`](/docs/references/backend/types/auth-object#has) helper to check if the user has the correct permission. If the user is not authorized, `has()` will return false, causing the loader to redirect the user to the `/request-access` route.
diff --git a/docs/quickstarts/express.mdx b/docs/quickstarts/express.mdx
index 4ce49c5754..f5dc8d6491 100644
--- a/docs/quickstarts/express.mdx
+++ b/docs/quickstarts/express.mdx
@@ -90,7 +90,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
## Add `clerkMiddleware()` to your application
- The [`clerkMiddleware()`](/docs/references/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/nextjs/auth-object#auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key.
+ The [`clerkMiddleware()`](/docs/references/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/backend/types/auth-object#auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key.
```ts {{ filename: 'index.ts', mark: [3, 7] }}
import 'dotenv/config'
diff --git a/docs/references/astro/clerk-middleware.mdx b/docs/references/astro/clerk-middleware.mdx
index c32f74ef31..e5d17f2e5b 100644
--- a/docs/references/astro/clerk-middleware.mdx
+++ b/docs/references/astro/clerk-middleware.mdx
@@ -56,7 +56,7 @@ export const onRequest = clerkMiddleware((auth, context) => {
### Protect routes based on user authorization status
-To protect routes based on user authorization status, use [`auth().has()`](/docs/references/nextjs/auth-object#has){{ target: '_blank' }} to check if the user has the required roles or permissions.
+To protect routes based on user authorization status, use [`auth().has()`](/docs/references/backend/types/auth-object#has){{ target: '_blank' }} to check if the user has the required roles or custom permissions.
```tsx {{ filename: 'src/middleware.ts' }}
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'
@@ -68,8 +68,8 @@ export const onRequest = clerkMiddleware((auth, context) => {
// Restrict admin routes to users with specific permissions
if (
- (isProtectedRoute(context.request) && !has({ permission: 'org:sys_memberships:manage' })) ||
- !has({ permission: 'org:sys_domains_manage' })
+ (isProtectedRoute(context.request) && !has({ permission: 'org:admin:example1' })) ||
+ !has({ permission: 'org:admin:example2' })
) {
// Add logic to run if the user does not have the required permissions; for example, redirecting to the sign-in page
return redirectToSignIn()
diff --git a/docs/references/astro/endpoints.mdx b/docs/references/astro/endpoints.mdx
index af3ce453e7..d3946b608b 100644
--- a/docs/references/astro/endpoints.mdx
+++ b/docs/references/astro/endpoints.mdx
@@ -27,7 +27,7 @@ export async function GET({ locals }) {
Clerk provides integrations with a number of popular databases.
-To retrieve a token from a JWT template and fetch data from an external source, use the [`getToken()`](/docs/references/nextjs/auth-object#get-token){{ target: '_blank' }} method from the [`auth()` local](/docs/references/astro/locals), as shown in the following example:
+To retrieve a token from a JWT template and fetch data from an external source, use the [`getToken()`](/docs/references/backend/types/auth-object#get-token){{ target: '_blank' }} method from the [`auth()` local](/docs/references/astro/locals), as shown in the following example:
```ts {{ filename: 'src/pages/api/route.ts' }}
export async function GET({ locals }) {
diff --git a/docs/references/astro/locals.mdx b/docs/references/astro/locals.mdx
index b2db7175ec..bca9ab05d2 100644
--- a/docs/references/astro/locals.mdx
+++ b/docs/references/astro/locals.mdx
@@ -3,11 +3,11 @@ title: Locals
description: Learn how to authenticate your Astro application with Clerk using locals.
---
-Through Astro [`locals`](https://docs.astro.build/en/guides/middleware/#storing-data-in-contextlocals), Clerk's [`Auth`](/docs/references/nextjs/auth-object){{ target: '_blank' }} and current [`User`](/docs/references/javascript/user/user){{ target: '_blank' }} objects can be accessed between middlewares and pages. These locals are injected when you install the provided [middleware](/docs/references/astro/clerk-middleware).
+Through Astro [`locals`](https://docs.astro.build/en/guides/middleware/#storing-data-in-contextlocals), Clerk's [`Auth`](/docs/references/backend/types/auth-object){{ target: '_blank' }} and current [`User`](/docs/references/javascript/user/user){{ target: '_blank' }} objects can be accessed between middlewares and pages. These locals are injected when you install the provided [middleware](/docs/references/astro/clerk-middleware).
The following guide provides examples of using the [`auth()`](/docs/references/nextjs/auth){{ target: '_blank' }} local to validate an authenticated user and the [`currentUser()`](/docs/references/nextjs/current-user){{ target: '_blank' }} local to access the [`Backend API User`](/docs/references/backend/types/backend-user){{ target: '_blank' }} object for the authenticated user.
-## Protect your pages
+## `locals.auth()`
You can use the `auth()` local to protect your pages and forms. It will return the current user's ID if they are signed in, or `null` if they are not. For more information on `auth()`, see the [reference](/docs/references/nextjs/auth){{ target: '_blank' }}.
@@ -43,7 +43,7 @@ You can use the `auth()` local to protect your pages and forms. It will return t
```
-## Accessing the current user
+## `locals.currentUser()`
Current user data is important for data enrichment. You can use the `currentUser()` local to fetch the current user's data in your pages.
diff --git a/docs/references/astro/overview.mdx b/docs/references/astro/overview.mdx
index 5c039c76a3..dbe0b11d70 100644
--- a/docs/references/astro/overview.mdx
+++ b/docs/references/astro/overview.mdx
@@ -36,7 +36,7 @@ The Astro SDK provides access to Clerk's authentication data through Astro's [`l
#### `Auth` object
-`Astro.locals.auth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their active organization ID. Learn more about the `Auth` object [here](/docs/references/nextjs/auth-object){{ target: '_blank' }}.
+`Astro.locals.auth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their active organization ID. Learn more about the `Auth` object [here](/docs/references/backend/types/auth-object){{ target: '_blank' }}.
### `clerkMiddleware()`
diff --git a/docs/references/backend/overview.mdx b/docs/references/backend/overview.mdx
index 48a87d65a9..ef24220996 100644
--- a/docs/references/backend/overview.mdx
+++ b/docs/references/backend/overview.mdx
@@ -351,7 +351,7 @@ The following options are available:
## Get the `userId` and other properties
-To access the [properties](/docs/references/nextjs/auth-object#auth-object-properties) of the authenticated user, such as their `userId` or `sessionId`, see the following examples:
+To access the [properties](/docs/references/backend/types/auth-object#auth-object-properties) of the authenticated user, such as their `userId` or `sessionId`, see the following examples:
diff --git a/docs/references/nextjs/auth-object.mdx b/docs/references/backend/types/auth-object.mdx
similarity index 83%
rename from docs/references/nextjs/auth-object.mdx
rename to docs/references/backend/types/auth-object.mdx
index 16f3011c3e..85f0a68ed8 100644
--- a/docs/references/nextjs/auth-object.mdx
+++ b/docs/references/backend/types/auth-object.mdx
@@ -3,9 +3,24 @@ title: Auth object
description: The Auth object contains information about the current user's session.
---
-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. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts.
+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.
-## `Auth` object properties
+## How to access the `Auth` object
+
+The `Auth` object is available on the `request` object in server contexts. Some frameworks provide a helper that returns the `Auth` object; see the following table for more information.
+
+| Framework | How to access the `Auth` object |
+| - | - |
+| Next.js App Router | [`auth()`](/docs/references/nextjs/auth) |
+| Next.js Pages Router | [`getAuth()`](/docs/references/nextjs/get-auth) |
+| Astro | [`locals.auth()`](/docs/references/astro/locals#locals-auth) |
+| Express | [`req.auth`](/docs/references/express/overview) |
+| React Router | [`getAuth()`](/docs/references/react-router/get-auth) |
+| Remix | [`getAuth()`](/docs/references/remix/read-session-data#get-auth) |
+| Tanstack Start | [`getAuth()`](/docs/references/tanstack-start/get-auth) |
+| Other | `request.auth` |
+
+## Properties
- `sessionId`
@@ -67,7 +82,7 @@ The `Auth` object contains important information like the current user's session
- [`has()`](#has)
- (isAuthorizedParams: [CheckAuthorizationParamsWithCustomPermissions](#check-authorization-params-with-custom-permissions)) => boolean
- A function that returns a boolean based on the permission or role provided as parameter. Can be used for authorization.
+ A function that checks if the user has an organization role or custom permission.
---
@@ -81,7 +96,7 @@ The `Auth` object contains important information like the current user's session
- [`getToken()`](#get-token)
- [`ServerGetToken`](#server-get-token)
- A function that returns a promise that resolves to the current user's session token. Can also be used to retrieve a custom JWT template.
+ 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).
---
@@ -101,11 +116,11 @@ The `orgRole` property on the `Auth` object has the type `OrganizationCustomRole
The `orgPermissions` property on the `Auth` object has the type `OrganizationCustomPermissionKey`.
-`OrganizationCustomPermissionKey` is a string that represents the permission of the user in the organization. Clerk provides [default System Permissions](/docs/organizations/roles-permissions#system-permissions), and you can create [custom permissions](/docs/organizations/create-roles-permissions#create-a-new-permission-for-your-organization).
+`OrganizationCustomPermissionKey` is a string that represents the permission of the user in the organization. Clerk provides [default system permissions](/docs/organizations/roles-permissions#system-permissions), and you can create [custom permissions](/docs/organizations/create-roles-permissions#create-a-new-permission-for-your-organization).
### `has()`
-`has()` determines if the user _has_ a role or permission.
+`has()` determines if the user _has_ a role or permission and returns a boolean value.
```ts
function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): boolean
@@ -189,14 +204,13 @@ The `ReverificationConfig` type has the following properties:
The age of the factor level to check for. Value should be greater than or equal to 1 and less than 99,999.
-#### `has()` permissions example
+#### `has()` authorization example
You can use `has()` to check if a user is authorized to access a component.
-In the following example:
+
-- `has()` is used to check if the user has the `org:team_settings:manage` permission.
-- If the user does not have the permission, `null` is returned and the "Team Settings" component is not rendered.
+In the following example, `has()` is used to check if the user has the `org:team_settings:manage` permission. If the user does not have the permission, `null` is returned and the page is not rendered. This example is written for Next.js App Router, but it can be adapted to other frameworks by using the appropriate method for accessing the `Auth` object.
```tsx {{ filename: 'app/page.tsx' }}
import { auth } from '@clerk/nextjs/server'
@@ -219,30 +233,21 @@ export default async function Page() {
You can use `has()` to check if a user has verified their credentials within a certain time frame.
-
+
### `getToken()`
-You can use `getToken()` on an `Auth` object to retrieve the user's session token. You can also use this method to retrieve a custom JWT template.
-
-Tokens can only be generated if the user is signed in.
-
-#### `ServerGetToken`
+`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).
```typescript
-type ServerGetToken = (options?: ServerGetTokenOptions) => Promise
-```
-
-#### `ServerGetTokenOptions`
+const getToken: ServerGetToken
-`getToken()` accepts an optional `options` parameter, which has the following properties:
-
-
- - `template?`
- - `string`
+type ServerGetToken = (options?: ServerGetTokenOptions) => Promise
- The name of the custom JWT template to retrieve.
-
+type ServerGetTokenOptions = {
+ template?: string // The name of the custom JWT template to retrieve.
+}
+```
#### Use `getToken()` in the frontend
diff --git a/docs/references/express/overview.mdx b/docs/references/express/overview.mdx
index 13264e7f47..52fcc449fd 100644
--- a/docs/references/express/overview.mdx
+++ b/docs/references/express/overview.mdx
@@ -16,7 +16,7 @@ See the [quickstart](/docs/quickstarts/express) to get started.
### `clerkMiddleware()`
-The `clerkMiddleware()` function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/nextjs/auth-object#auth-object) object to the request object under the `auth` key.
+The `clerkMiddleware()` function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/backend/types/auth-object#auth-object) object to the request object under the `auth` key.
```js
import { clerkMiddleware } from '@clerk/express'
@@ -102,7 +102,7 @@ const hasPermission = (req, res, next) => {
const auth = getAuth(req)
// Handle if the user is not authorized
- if (!auth.has({ permission: 'org:admin:testpermission' })) {
+ if (!auth.has({ permission: 'org:admin:example' })) {
return res.status(403).send('Forbidden')
}
diff --git a/docs/references/ios/get-token.mdx b/docs/references/ios/get-token.mdx
index 13e3eb3528..7c7f631894 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.
---
-Retrieves the user's session token for the [default Clerk token](/docs/backend-requests/resources/session-tokens) or the given [JWT template](/docs/backend-requests/making/jwt-templates).
+Retrieves the user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-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 87a0196a95..2011e03a06 100644
--- a/docs/references/javascript/session.mdx
+++ b/docs/references/javascript/session.mdx
@@ -137,7 +137,7 @@ function touch(): Promise
### `getToken()`
-Retrieves the user's session token for the default Clerk token or the given template.
+Retrieves the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-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.
@@ -249,7 +249,7 @@ type CheckAuthorizationParams =
---
- `reverification?`
- - [ReverificationConfig](/docs/references/nextjs/auth-object#reverification-config)
+ - [ReverificationConfig](/docs/references/backend/types/auth-object#reverification-config)
The reverification configuration to check for.
diff --git a/docs/references/nextjs/auth.mdx b/docs/references/nextjs/auth.mdx
index d4558edaca..000e1468f8 100644
--- a/docs/references/nextjs/auth.mdx
+++ b/docs/references/nextjs/auth.mdx
@@ -3,7 +3,7 @@ title: '`auth()`'
description: Access minimal authentication data for managing sessions and data fetching.
---
-The `auth()` helper returns the [`Auth`](/docs/references/nextjs/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.
- Only available for App Router.
- Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions.
@@ -20,7 +20,7 @@ The following table describes how `auth.protect()` behaves based on user authent
| Authenticated | Authorized | `auth.protect()` will |
| - | - | - |
-| Yes | Yes | Return the [`Auth`](/docs/references/nextjs/auth-object) object. |
+| Yes | Yes | Return the [`Auth`](/docs/references/backend/types/auth-object) object. |
| Yes | No | Return a `404` error. |
| No | No | Redirect the user to the sign-in page\*. |
@@ -47,7 +47,7 @@ The following table describes how `auth.protect()` behaves based on user authent
- `has?`
- `(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean`
- A function that returns a boolean based on the permission or role provided as parameter. Can be used for authorization. See [the dedicated `has()` section](/docs/references/nextjs/auth-object#has) for more information.
+ A function that checks if the user has an organization role or custom permission. See the [reference](/docs/references/backend/types/auth-object#has) for more information.
---
@@ -100,7 +100,7 @@ export default async function Page() {
}
```
-## Use `auth()` to retrieve `userId`
+## Use `auth()` to protect pages
You can use `auth()` to check if a `userId` exists. If it does not, that means there is no user signed in. You can use this information to protect pages, as shown in the following example:
@@ -116,6 +116,14 @@ export default async function Page() {
}
```
+## Use `auth()` in API routes
+
+See detailed examples in the [dedicated guide](/docs/references/nextjs/read-session-data).
+
+## Use `auth()` to check roles and permissions
+
+You can use `auth()` to check if a user is authorized to access certain parts of your application or even entire routes. See detailed examples in the [dedicated guide](/docs/organizations/verify-user-permissions).
+
## Use `auth()` for data fetching
When using a Clerk integration, or if you need to send a JWT along to a server, you can use the `getToken()` function that is returned by `auth()`.
@@ -143,7 +151,3 @@ export async function GET() {
}
}
```
-
-## Use `auth()` to protect your app
-
-You can protect certain parts of your application or even entire routes based on a user's authentication and/or authorization status. See detailed examples in the [dedicated guide](/docs/organizations/verify-user-permissions).
diff --git a/docs/references/nextjs/clerk-middleware.mdx b/docs/references/nextjs/clerk-middleware.mdx
index 1403953e07..2411a67eb9 100644
--- a/docs/references/nextjs/clerk-middleware.mdx
+++ b/docs/references/nextjs/clerk-middleware.mdx
@@ -1,6 +1,6 @@
---
-title: '`clerkMiddleware()` | Next.js'
-description: The `clerkMiddleware()` function allows you to protect your Next.js application using Middleware.
+title: clerkMiddleware() | Next.js
+description: The clerkMiddleware() function allows you to protect your Next.js application using Middleware.
---
The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers.
@@ -41,16 +41,16 @@ In the following example, `createRouteMatcher()` sets all `/dashboard` and `/for
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/forum(.*)'])
```
-## Protect routes
+## Protect API routes
-You can protect routes by checking either or both of the following:
+You can protect routes using either or both of the following:
-- [User authentication status](#protect-routes-based-on-user-authentication-status) (user is signed in or out)
-- [User authorization status](#protect-routes-based-on-user-authorization-status) (user has the required role or permission)
+- [Authentication-based protection](#protect-routes-based-on-authentication-status): Verify if the user is signed in.
+- [Authorization-based protection](#protect-routes-based-on-authorization-status): Verify if the user has the required organization roles or custom permissions.
-### Protect routes based on user authentication status
+### Protect routes based on authentication status
-You can protect routes based on user authentication status by checking if the user is signed in.
+You can protect routes based on a user's authentication status by checking if the user is signed in.
There are two methods that you can use:
@@ -103,77 +103,80 @@ There are two methods that you can use:
```
-### Protect routes based on user authorization status
+### Protect routes based on authorization status
-You can protect routes based on user authorization status by checking if the user has the required roles or permissions.
+You can protect routes based on a user's authorization status by checking if the user has the required roles or permissions.
There are two methods that you can use:
- Use [`auth.protect()`](/docs/references/nextjs/auth#protect) if you want Clerk to return a `404` if the user does not have the role or permission.
-- Use [`auth().has()`](/docs/references/nextjs/auth-object#has) if you want more control over what your app does based on the authorization status.
-
-
- ```tsx {{ filename: 'middleware.ts' }}
- import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
-
- const isProtectedRoute = createRouteMatcher(['/admin(.*)'])
+- Use [`auth().has()`](/docs/references/backend/types/auth-object#has) if you want more control over what your app does based on the authorization status.
+
+
+
+ ```tsx {{ filename: 'middleware.ts' }}
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+
+ const isProtectedRoute = createRouteMatcher(['/admin(.*)'])
+
+ export default clerkMiddleware(async (auth, req) => {
+ // Restrict admin routes to users with specific permissions
+ if (isProtectedRoute(req)) {
+ await auth.protect((has) => {
+ return has({ permission: 'org:admin:example1' }) || has({ permission: 'org:admin:example2' })
+ })
+ }
+ })
- export default clerkMiddleware(async (auth, req) => {
- // Restrict admin routes to users with specific permissions
- if (isProtectedRoute(req)) {
- await auth.protect((has) => {
- return (
- has({ permission: 'org:sys_memberships:manage' }) ||
- has({ permission: 'org:sys_domains_manage' })
- )
- })
+ export const config = {
+ matcher: [
+ // Skip Next.js internals and all static files, unless found in search params
+ '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+ // Always run for API routes
+ '/(api|trpc)(.*)',
+ ],
}
- })
+ ```
+
- export const config = {
- matcher: [
- // Skip Next.js internals and all static files, unless found in search params
- '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
- // Always run for API routes
- '/(api|trpc)(.*)',
- ],
- }
- ```
+
+
- ```tsx {{ filename: 'middleware.ts' }}
- import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+ ```tsx {{ filename: 'middleware.ts' }}
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
- const isProtectedRoute = createRouteMatcher(['/admin(.*)'])
+ const isProtectedRoute = createRouteMatcher(['/admin(.*)'])
- export default clerkMiddleware(async (auth, req) => {
- const { has, redirectToSignIn } = await auth()
- // Restrict admin routes to users with specific permissions
- if (
- (isProtectedRoute(req) && !has({ permission: 'org:sys_memberships:manage' })) ||
- !has({ permission: 'org:sys_domains_manage' })
- ) {
- // Add logic to run if the user does not have the required permissions
+ export default clerkMiddleware(async (auth, req) => {
+ const { has, redirectToSignIn } = await auth()
+ // Restrict admin routes to users with specific permissions
+ if (
+ (isProtectedRoute(req) && !has({ permission: 'org:admin:example1' })) ||
+ !has({ permission: 'org:admin:example2' })
+ ) {
+ // Add logic to run if the user does not have the required permissions
- return redirectToSignIn()
- }
- })
+ return redirectToSignIn()
+ }
+ })
- export const config = {
- matcher: [
- // Skip Next.js internals and all static files, unless found in search params
- '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
- // Always run for API routes
- '/(api|trpc)(.*)',
- ],
- }
- ```
-
+ export const config = {
+ matcher: [
+ // Skip Next.js internals and all static files, unless found in search params
+ '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+ // Always run for API routes
+ '/(api|trpc)(.*)',
+ ],
+ }
+ ```
+
+
## Protect multiple groups of routes
You can use more than one `createRouteMatcher()` in your application if you have two or more groups of routes.
-The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) method from the `auth()` helper.
+The following example uses the [`has()`](/docs/references/backend/types/auth-object#has) method from the `auth()` helper.
```tsx {{ filename: 'middleware.ts' }}
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
@@ -186,10 +189,7 @@ export default clerkMiddleware(async (auth, req) => {
// Restrict admin routes to users with specific permissions
if (isTenantAdminRoute(req)) {
await auth.protect((has) => {
- return (
- has({ permission: 'org:sys_memberships:manage' }) ||
- has({ permission: 'org:sys_domains_manage' })
- )
+ return has({ permission: 'org:admin:example1' }) || has({ permission: 'org:admin:example2' })
})
}
// Restrict organization routes to signed in users
diff --git a/docs/references/nextjs/get-auth.mdx b/docs/references/nextjs/get-auth.mdx
index 4f6fe83407..1b96d951ca 100644
--- a/docs/references/nextjs/get-auth.mdx
+++ b/docs/references/nextjs/get-auth.mdx
@@ -26,30 +26,13 @@ The `getAuth()` helper retrieves authentication state from the request object.
## Returns
-`getAuth()` returns the [`Auth`](/docs/references/nextjs/auth-object) object.
+`getAuth()` returns the `Auth` object. See the [`Auth` reference](/docs/references/backend/types/auth-object) for more information.
## Usage
-### Basic usage
-
-The following example demonstrates how to use `getAuth()` to retrieve authentication information in an API route.
-
-```tsx {{ filename: 'app/api/example/route.ts' }}
-import { getAuth } from '@clerk/nextjs/server'
-import type { NextApiRequest, NextApiResponse } from 'next'
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
- const { userId } = getAuth(req)
-
- // Add logic that retrieves the data for the API route
-
- return res.status(200).json({ userId: userId })
-}
-```
-
### Protect API routes
-It is important to protect your API routes to ensure that only authenticated users can access them. You can do this by checking if the `userId` is present in the `getAuth()` response, like in the following example:
+The following example demonstrates how to protect an API route by checking if the `userId` is present in the `getAuth()` response.
```tsx {{ filename: 'app/api/example/route.ts' }}
import { getAuth } from '@clerk/nextjs/server'
@@ -70,7 +53,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
### Usage with `getToken()`
-`getAuth()` returns `getToken()`, which is a method that returns the current user's session token. You can also use this function to retrieve a custom JWT template, like in the following example:
+`getAuth()` returns [`getToken()`](/docs/references/backend/types/auth-object#get-token), which is a method that returns the current user's session token or a custom JWT template.
```tsx {{ filename: 'app/api/example/route.ts' }}
import { getAuth } from '@clerk/nextjs/server'
@@ -90,7 +73,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
### Usage with `clerkClient`
-`clerkClient` is used to access the [Backend SDK](/docs/references/backend/overview), which exposes Clerk's Backend API resources. You can use `getAuth()` to pass authentication information that many of the Backend SDK methods require, like in the following example:
+`clerkClient` is used to access the [Backend SDK](/docs/references/backend/overview), which exposes Clerk's Backend API resources. You can use `getAuth()` to pass authentication information that many of the Backend SDK methods require, like the user's ID.
```tsx {{ filename: 'app/api/example/route.ts' }}
import { clerkClient, getAuth } from '@clerk/nextjs/server'
diff --git a/docs/references/nextjs/overview.mdx b/docs/references/nextjs/overview.mdx
index 4e4ede8b37..2e1913309c 100644
--- a/docs/references/nextjs/overview.mdx
+++ b/docs/references/nextjs/overview.mdx
@@ -31,7 +31,7 @@ Clerk continues to provide drop-in support for the Next.js Pages Router. In addi
## `Auth` object
-Both `auth()` (App Router) and `getAuth()` (Pages Router) return an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}.
+Both `auth()` (App Router) and `getAuth()` (Pages Router) return an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/backend/types/auth-object){{ target: '_blank' }}.
## `clerkMiddleware()`
diff --git a/docs/references/nextjs/read-session-data.mdx b/docs/references/nextjs/read-session-data.mdx
index 11d9cb5134..8fceb5fe56 100644
--- a/docs/references/nextjs/read-session-data.mdx
+++ b/docs/references/nextjs/read-session-data.mdx
@@ -11,7 +11,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/nextjs/auth-object) object of the currently active user. Now that request data is available in the global scope through Next.js's `headers()` and `cookies()` methods, passing the request object to Clerk is no longer required.
+The `auth()` helper will return the [`Auth`](/docs/references/backend/types/auth-object) object of the currently active user. Now that request data is available in the global scope through Next.js's `headers()` and `cookies()` methods, passing the request object to Clerk is no longer required.
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.
@@ -53,6 +53,7 @@ Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backen
// Get the userId from auth() -- if null, the user is not signed in
const { userId } = await auth()
+ // Protect the route by checking if the user is signed in
if (!userId) {
return new NextResponse('Unauthorized', { status: 401 })
}
diff --git a/docs/references/nextjs/route-handlers.mdx b/docs/references/nextjs/route-handlers.mdx
index 2e300201ad..fea9f74abc 100644
--- a/docs/references/nextjs/route-handlers.mdx
+++ b/docs/references/nextjs/route-handlers.mdx
@@ -48,7 +48,7 @@ If you aren't protecting your Route Handler using [`clerkMiddleware()`](/docs/re
Clerk provides integrations with a number of popular databases.
-The following example demonstrates how to use [`auth().getToken()`](/docs/references/nextjs/auth-object#get-token) to retrieve a token from a JWT template and use it to fetch data from the external source.
+The following example demonstrates how to use [`auth().getToken()`](/docs/references/backend/types/auth-object#get-token) to retrieve a token from a JWT template and use it to fetch data from the external source.
```ts {{ filename: 'app/api/route.ts' }}
import { NextResponse } from 'next/server'
diff --git a/docs/references/nextjs/trpc.mdx b/docs/references/nextjs/trpc.mdx
index 941b53f608..af24bae573 100644
--- a/docs/references/nextjs/trpc.mdx
+++ b/docs/references/nextjs/trpc.mdx
@@ -29,7 +29,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica
## Create Clerk authentication context
- Clerk's [`Auth`](/docs/references/nextjs/auth-object) object includes important authentication information like the current user's session ID, user ID, and organization ID. It also contains methods to check for the current user's permissions and to retrieve their session token.
+ Clerk's [`Auth`](/docs/references/backend/types/auth-object) object includes important authentication information like the current user's session ID, user ID, and organization ID. It also contains methods to check for the current user's permissions and to retrieve their session token.
To add Clerk's authentication context (`Auth` object) to your tRPC server, create a context file that will be used to create the context for every tRPC query sent to the server. This context file will use the [`getAuth()`](/docs/references/nextjs/get-auth) helper from Clerk to access the user's `Auth` object.
diff --git a/docs/references/react-router/get-auth.mdx b/docs/references/react-router/get-auth.mdx
index 3707ba4fcd..8cd2f02ebb 100644
--- a/docs/references/react-router/get-auth.mdx
+++ b/docs/references/react-router/get-auth.mdx
@@ -23,7 +23,7 @@ The `getAuth()` helper retrieves the current user's authentication state from th
## Returns
-`getAuth()` returns the [`Auth`](/docs/references/nextjs/auth-object){{ target: '_blank' }} object.
+`getAuth()` returns the [`Auth`](/docs/references/backend/types/auth-object){{ target: '_blank' }} object.
## Usage
diff --git a/docs/references/react-router/overview.mdx b/docs/references/react-router/overview.mdx
index e101972576..c7b3b2c883 100644
--- a/docs/references/react-router/overview.mdx
+++ b/docs/references/react-router/overview.mdx
@@ -23,7 +23,7 @@ The following references show how to integrate Clerk features into applications
### `Auth` object
-The `getAuth()` method returns an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}.
+The `getAuth()` method returns an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/backend/types/auth-object){{ target: '_blank' }}.
## React Router implementations
diff --git a/docs/references/react/use-auth.mdx b/docs/references/react/use-auth.mdx
index 755e0fb304..6e443aee3f 100644
--- a/docs/references/react/use-auth.mdx
+++ b/docs/references/react/use-auth.mdx
@@ -72,7 +72,7 @@ The `useAuth()` hook provides access to the current user's authentication state
- `has()`
- `(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean`
- A function that checks if the user has specific permissions or roles. See the [reference doc](/docs/references/nextjs/auth-object#has).
+ A function that checks if the user has specific permissions or roles. See the [reference doc](/docs/references/backend/types/auth-object#has).
## How to use the `useAuth()` hook
diff --git a/docs/references/remix/read-session-data.mdx b/docs/references/remix/read-session-data.mdx
index c1d54803d1..a65cf9403a 100644
--- a/docs/references/remix/read-session-data.mdx
+++ b/docs/references/remix/read-session-data.mdx
@@ -9,7 +9,7 @@ Clerk provides a set of [hooks and helpers](/docs/references/nextjs/overview#cli
### `getAuth()`
-The [`getAuth()`](/docs/references/nextjs/get-auth){{ target: '_blank' }} helper allows you to access the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}, which includes the current user's `userId`. You can use the `userId` to protect your routes or get the user's data.
+The [`getAuth()`](/docs/references/nextjs/get-auth){{ target: '_blank' }} helper allows you to access the [`Auth` object](/docs/references/backend/types/auth-object){{ target: '_blank' }}, which includes the current user's `userId`. You can use the `userId` to protect your routes or get the user's data.
In the following example, the `userId` is passed to the Backend SDK's [`getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} method to get the user's full `User` object. For information on how to use the Backend SDK, see the [Backend SDK documentation](/docs/references/backend/overview){{ target: '_blank' }}.
diff --git a/docs/references/sdk/backend-only.mdx b/docs/references/sdk/backend-only.mdx
index 26ed2bbd9b..e8c13906bf 100644
--- a/docs/references/sdk/backend-only.mdx
+++ b/docs/references/sdk/backend-only.mdx
@@ -71,7 +71,7 @@ You can manually create a wrapper library around the [BAPI OpenAPI](https://cler
### Create your middleware/plugin
- Inside the middleware, you’ll use the user-provided Clerk client (or use the default one created in the previous step) and authenticate the request. [`authenticateRequest`](/docs/references/backend/authenticate-request) returns `Promise`. The middleware should set `requestState.toAuth()` into its context as this will contain the resolved signed-in/signed-out [`Auth`](/docs/references/nextjs/auth-object) object. This way other helpers can access it later in the chain.
+ Inside the middleware, you’ll use the user-provided Clerk client (or use the default one created in the previous step) and authenticate the request. [`authenticateRequest`](/docs/references/backend/authenticate-request) returns `Promise`. The middleware should set `requestState.toAuth()` into its context as this will contain the resolved signed-in/signed-out [`Auth`](/docs/references/backend/types/auth-object) object. This way other helpers can access it later in the chain.
```ts {{ filename: 'clerk-middleware.ts' }}
import { clerkClient as defaultClerkClient } from './client.ts'
@@ -143,7 +143,7 @@ You can manually create a wrapper library around the [BAPI OpenAPI](https://cler
app.get('/path', requireAuth())
```
- Your end-users will also have access to a [`has()`](/docs/references/nextjs/auth-object#has) function on the [`Auth`](/docs/references/nextjs/auth-object) object. They can combine it with `requireAuth()` like so:
+ Your end-users will also have access to a [`has()`](/docs/references/backend/types/auth-object#has) function on the [`Auth`](/docs/references/backend/types/auth-object) object. They can combine it with `requireAuth()` like so:
```ts {{ filename: 'index.ts' }}
const app = new Framework()
diff --git a/docs/references/tanstack-start/get-auth.mdx b/docs/references/tanstack-start/get-auth.mdx
index 60d70fbddc..c4c935892e 100644
--- a/docs/references/tanstack-start/get-auth.mdx
+++ b/docs/references/tanstack-start/get-auth.mdx
@@ -23,7 +23,7 @@ The `getAuth()` helper retrieves authentication state from the request object.
## Returns
-`getAuth()` returns the [`Auth`](/docs/references/nextjs/auth-object){{ target: '_blank' }} object.
+`getAuth()` returns the [`Auth`](/docs/references/backend/types/auth-object){{ target: '_blank' }} object.
## Usage
diff --git a/docs/references/tanstack-start/overview.mdx b/docs/references/tanstack-start/overview.mdx
index e27636771a..f112908324 100644
--- a/docs/references/tanstack-start/overview.mdx
+++ b/docs/references/tanstack-start/overview.mdx
@@ -24,4 +24,4 @@ The following references show how to integrate Clerk features into applications
### `Auth` object
-The `getAuth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their organization ID. Learn more about the `Auth` object [here](/docs/references/nextjs/auth-object).
+The `getAuth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their organization ID. Learn more about the `Auth` object [here](/docs/references/backend/types/auth-object).
diff --git a/docs/users/metadata.mdx b/docs/users/metadata.mdx
index a962fe534a..211bce1488 100644
--- a/docs/users/metadata.mdx
+++ b/docs/users/metadata.mdx
@@ -281,7 +281,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/nextjs/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/backend-requests/making/custom-session-token).
## Unsafe metadata
@@ -512,4 +512,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/nextjs/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/backend-requests/making/custom-session-token).