āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/nextjs/app-router/auth ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
auth()'
description: Access minimal authentication data for managing sessions and data fetching.
sdk: nextjsThe auth() helper returns the Auth{{ target: '_blank' }} 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.
clerkMiddleware() to be configured.An optional object that can be used to configure the behavior of the auth() function. It accepts the following properties:
treatPendingAsSignedOut?: A boolean that indicates whether to treat pending session status as signed out. Defaults to true.
</Properties>
auth.protect()auth includes a single property, the protect() method, which you can use in three ways:
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{{ target: '_blank' }} object. |
| Yes | No | Return a 404 error. |
| No | No | Redirect the user to the sign-in page**. |
[!IMPORTANT] For non-document requests, such as API requests,
auth.protect()returns:
- A
404error for unauthenticated requests with session token type.- A
401error for unauthenticated requests with machine token types.
auth.protect() accepts the following parameters:
The role to check for.
permission?stringThe permission to check for.
has?(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => booleanA function that checks if the user has an organization role or custom permission. See the reference for more information.
unauthorizedUrl?stringThe URL to redirect the user to if they are not authorized.
unauthenticatedUrl?stringThe URL to redirect the user to if they are not authenticated.
token?TokenTypeThe type of authentication token(s) to accept. Valid values are:
'session_token' - authenticates a user session.'oauth_token' - authenticates a machine request using OAuth.'machine_token' - authenticates a machine to machine request.'api_key' - authenticates a machine request using API keys.Can be set to:
'any' to accept all available token types.Defaults to 'session_token'.
</Properties>
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.
The auth() helper returns the following:
Auth{{ target: '_blank' }} object.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:
The URL to redirect the user back to after they sign in. </Properties>
[!NOTE]
auth()on the server-side can only access redirect URLs defined via environment variables orclerkMiddlewaredynamic keys.
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 { isAuthenticated, redirectToSignIn, userId } = await auth()
if (!isAuthenticated) return redirectToSignIn()
return <h1>Hello, {userId}</h1>
}
auth() usageYou can use auth() to check if isAuthenticated is true. If it's false, then there is not an authenticated (signed in) user. See detailed examples in the dedicated guide.
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.
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.
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{{ target: '_blank' }}.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā