auth()
The auth() helper returns the Auth object of the currently active user, as well as the redirectToSignIn() method. It includes a single method, protect(), which you can use to check if a user is authenticated or authorized to access certain parts of your application or even entire routes.
- Only available for App Router.
- Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions.
- Requires
clerkMiddleware()to be configured.
Parameters
- Name
acceptsToken?- Type
TokenType- Description
The type of authentication token(s) to accept. Valid values are:
'session_token''oauth_token''machine_token''api_key'
Can be set to:
- A single token type.
- An array of token types.
'any'to accept all available token types.
Defaults to
'session_token'.
auth.protect()
auth includes a single property, the protect() method, which you can use in three ways:
- to check if a user is authenticated (signed in)
- to check if a user is authorized (has the correct roles or permissions) to access something, such as a component or a route handler
- to check if a request includes a valid machine token (e.g. API key or OAuth token) and enforce access rules accordingly
The following table describes how auth.protect() behaves based on user authentication or authorization status:
| Authenticated | Authorized | auth.protect() will |
|---|---|---|
| Yes | Yes | Return the Auth object. |
| Yes | No | Return a 404 error. |
| No | No | Redirect the user to the sign-in page**. |
auth.protect() accepts the following parameters:
- Name
role?- Type
string- Description
The role to check for.
- Name
permission?- Type
string- Description
The permission to check for.
- Name
has?- Type
(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean- Description
A function that checks if the user has an organization role or custom permission. See the reference for more information.
- Name
unauthorizedUrl?- Type
string- Description
The URL to redirect the user to if they are not authorized.
- Name
unauthenticatedUrl?- Type
string- Description
The URL to redirect the user to if they are not authenticated.
- Name
token?- Type
TokenType- Description
The type of authentication token(s) to accept. Valid values are:
'session_token''oauth_token''machine_token''api_key'
Can be set to:
- A single token type.
- An array of token types.
'any'to accept all available token types.
Defaults to
'session_token'.
Example
auth.protect() can be used to check if a user is authenticated or authorized to access certain parts of your application or even entire routes. See detailed examples in the guide on verifying if a user is authorized.
Returns
The auth() helper returns the following:
- The
Authobject. - The
redirectToSignIn()method.
redirectToSignIn()
The auth() helper returns the redirectToSignIn() method, which you can use to redirect the user to the sign-in page.
redirectToSignIn() accepts the following parameters:
- Name
returnBackUrl?- Type
string | URL- Description
The URL to redirect the user back to after they sign in.
Example
The following example shows how to use redirectToSignIn() to redirect the user to the sign-in page if they are not authenticated. It's also common to use redirectToSignIn() in clerkMiddleware() to protect entire routes; see the clerkMiddleware() docs for more information.
import { auth } from '@clerk/nextjs/server'
export default async function Page() {
const { userId, redirectToSignIn } = await auth()
if (!userId) return redirectToSignIn()
return <h1>Hello, {userId}</h1>
}auth() usage
Protect pages and routes
You can use auth() to check if a userId exists. If it's null, then there is not an authenticated (signed in) user. See detailed examples in the dedicated guide.
Check if a user is authorized
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 type of access control. See detailed examples in the guide on verifying if a user is authorized.
Verify machine requests
You can use auth() to verify OAuth access tokens by passing in the acceptsToken parameter. See detailed examples in the guide on verifying OAuth access tokens.
Data fetching with getToken()
If you need to send a JWT along to a server, getToken() retrieves the current user's session token or a custom JWT template. See detailed examples in the Auth object reference.
Feedback
Last updated on