useAuth()

The useAuth() hook provides access to the current user's authentication state and methods to manage the active session.

Note

To access auth data server-side, see the Auth object reference doc.

By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the dynamic prop to <ClerkProvider>. See the guide on rendering modes for more information, including code examples.

Parameters

Name
initialAuthStateOrOptions?
Type
null | { treatPendingAsSignedOut: boolean; } | Record<string, any>
Description
An object containing the initial authentication state or options for the useAuth() hook. If not provided, the hook will attempt to derive the state from the context. treatPendingAsSignedOut is a boolean that indicates whether pending sessions are considered as signed out or not. Defaults to true.

Returns

This function returns a discriminated union type. There are multiple variants of this type available which you can select by clicking on one of the tabs.

Initialization

Signed out

Signed in (no active organization)

Signed in (with active organization)

Name
actor
Type
undefined
Description
The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
Name
getToken()
Type
(options?) => Promise<null | string>
Description
A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the reference doc.
Name
has
Type
undefined
Description
A function that checks if the user has specific permissions or roles. See the reference doc.
Name
isLoaded
Type
false
Description
A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
Name
isSignedIn
Type
undefined
Description
A boolean that indicates whether a user is currently signed in.
Name
orgId
Type
undefined
Description
The ID of the user's active organization.
Name
orgRole
Type
undefined
Description
The current user's role in their active organization.
Name
orgSlug
Type
undefined
Description
The URL-friendly identifier of the user's active organization.
Name
sessionClaims
Type
undefined
Description
The current user's session claims.
Name
sessionId
Type
undefined
Description
The ID for the current session.
Name
signOut()
Type
{ (options?): Promise<void>; (signOutCallback?, options?): Promise<void>; }
Description
A function that signs out the current user. Returns a promise that resolves when complete. See the reference doc.
Name
userId
Type
undefined
Description
The ID of the current user.

Name
actor
Type
null
Description
The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
Name
getToken()
Type
(options?) => Promise<null | string>
Description
A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the reference doc.
Name
has()
Type
(params) => false
Description
A function that checks if the user has specific permissions or roles. See the reference doc.
Name
isLoaded
Type
true
Description
A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
Name
isSignedIn
Type
false
Description
A boolean that indicates whether a user is currently signed in.
Name
orgId
Type
null
Description
The ID of the user's active organization.
Name
orgRole
Type
null
Description
The current user's role in their active organization.
Name
orgSlug
Type
null
Description
The URL-friendly identifier of the user's active organization.
Name
sessionClaims
Type
null
Description
The current user's session claims.
Name
sessionId
Type
null
Description
The ID for the current session.
Name
signOut()
Type
{ (options?): Promise<void>; (signOutCallback?, options?): Promise<void>; }
Description
A function that signs out the current user. Returns a promise that resolves when complete. See the reference doc.
Name
userId
Type
null
Description
The ID of the current user.

Name
actor
Type
null | { [x: string]: unknown; sub: string; }
Description
The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
Name
getToken()
Type
(options?) => Promise<null | string>
Description
A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the reference doc.
Name
has()
Type
(isAuthorizedParams) => boolean
Description
A function that checks if the user has specific permissions or roles. See the reference doc.
Name
isLoaded
Type
true
Description
A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
Name
isSignedIn
Type
true
Description
A boolean that indicates whether a user is currently signed in.
Name
orgId
Type
null
Description
The ID of the user's active organization.
Name
orgRole
Type
null
Description
The current user's role in their active organization.
Name
orgSlug
Type
null
Description
The URL-friendly identifier of the user's active organization.
Name
sessionClaims
Type
JwtPayload
Description
The current user's session claims.
Name
sessionId
Type
string
Description
The ID for the current session.
Name
signOut()
Type
{ (options?): Promise<void>; (signOutCallback?, options?): Promise<void>; }
Description
A function that signs out the current user. Returns a promise that resolves when complete. See the reference doc.
Name
userId
Type
string
Description
The ID of the current user.

Name
actor
Type
null | { [x: string]: unknown; sub: string; }
Description
The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
Name
getToken()
Type
(options?) => Promise<null | string>
Description
A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the reference doc.
Name
has()
Type
(isAuthorizedParams) => boolean
Description
A function that checks if the user has specific permissions or roles. See the reference doc.
Name
isLoaded
Type
true
Description
A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
Name
isSignedIn
Type
true
Description
A boolean that indicates whether a user is currently signed in.
Name
orgId
Type
string
Description
The ID of the user's active organization.
Name
orgRole
Type
OrganizationCustomRoleKey
Description
The current user's role in their active organization.
Name
orgSlug
Type
null | string
Description
The URL-friendly identifier of the user's active organization.
Name
sessionClaims
Type
JwtPayload
Description
The current user's session claims.
Name
sessionId
Type
string
Description
The ID for the current session.
Name
signOut()
Type
{ (options?): Promise<void>; (signOutCallback?, options?): Promise<void>; }
Description
A function that signs out the current user. Returns a promise that resolves when complete. See the reference doc.
Name
userId
Type
string
Description
The ID of the current user.

Example

The following example demonstrates how to use the useAuth() hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the getToken() method to retrieve a session token for fetching data from an external resource.

React

Next.js

src/pages/ExternalDataPage.tsx

import { useAuth } from "@clerk/clerk-react";

export default function ExternalDataPage() {
  const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();

  const fetchExternalData = async () => {
    const token = await getToken();

    // Fetch data from an external API
    const response = await fetch("https://api.example.com/data", {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    return response.json();
  };

  if (!isLoaded) {
    return <div>Loading...</div>;
  }

  if (!isSignedIn) {
    return <div>Sign in to view this page</div>;
  }

  return (
    <div>
      <p>
        Hello, {userId}! Your current active session is {sessionId}.
      </p>
      <button onClick={fetchExternalData}>Fetch Data</button>
    </div>
  );
}

app/external-data/page.tsx

"use client";

import { useAuth } from "@clerk/nextjs";

export default function ExternalDataPage() {
  const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();

  const fetchExternalData = async () => {
    const token = await getToken();

    // Fetch data from an external API
    const response = await fetch("https://api.example.com/data", {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    return response.json();
  };

  if (!isLoaded) {
    return <div>Loading...</div>;
  }

  if (!isSignedIn) {
    return <div>Sign in to view this page</div>;
  }

  return (
    <div>
      <p>
        Hello, {userId}! Your current active session is {sessionId}.
      </p>
      <button onClick={fetchExternalData}>Fetch Data</button>
    </div>
  );
}

Edit this page on GitHub

Last updated on Apr 22, 2025

useAuth()

Parameters

Returns

Example

Feedback