# Auth object 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. > The structure of the `Auth` object varies depending on the type of request. > For machine-authenticated requests (e.g. using an API key or OAuth token), the object reflects machine-level authentication data instead of user session details. > > If you're working with machine-authenticated requests, refer to the [Machine properties section](#machine-properties) for a detailed breakdown. ## 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()](https://clerk.com/docs/reference/nextjs/app-router/auth.md) | | Next.js Pages Router | [getAuth()](https://clerk.com/docs/reference/nextjs/pages-router/get-auth.md) | | Astro | [locals.auth()](https://clerk.com/docs/reference/astro/locals.md#locals-auth) | | Express | [`req.auth`](https://clerk.com/docs/reference/express/overview.md) | | Fastify | [getAuth()](https://clerk.com/docs/reference/fastify/get-auth.md) | | Nuxt | [event.context.auth()](https://clerk.com/docs/reference/nuxt/overview.md#auth-object) | | React Router | [getAuth()](https://clerk.com/docs/reference/react-router/get-auth.md) | | TanStack React Start | [auth()](https://clerk.com/docs/reference/tanstack-react-start/auth.md) | | Other | `request.auth` | ## Session properties | Name | Type | Description | | --------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | actor | ActClaim | undefined | Holds identifier for the user that is impersonating the current user. Read more about impersonation. | | debug | AuthObjectDebug | Used to help debug issues when using Clerk in development. | | factorVerificationAge | [number, number] | null | An array where each item represents the number of minutes since the last verification of a first factorFirst factor is the first factor of authentication that is required to complete the authentication process. For example, when a user signs in with email and password, the password is the first factor. First factor verification is the process of verifying a user's identity using a single factor. This can be compared to second factor verificationSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor.., also known as two-factor authentication (2FA) or multi-factor authentication (MFA), where the user needs to provide an additional factor to verify their identity. or second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor..: [firstFactorAge, secondFactorAge]. | | getToken() | ServerGetToken | A function that gets the current user's session token or a custom JWT template. | | has() | (isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean | A function that checks if the user has an Organization Role or custom Permission. | | orgId | string | undefined | The ID of the user's Active OrganizationA user can be a member of multiple Organizations, but only one can be active at a time. The Active Organization determines which Organization-specific data the user can access and which Role and related Permissions they have within the Organization.. | | orgPermissions | OrganizationCustomPermissionKey[] | undefined | The current user's Active OrganizationA user can be a member of multiple Organizations, but only one can be active at a time. The Active Organization determines which Organization-specific data the user can access and which Role and related Permissions they have within the Organization. permissions. | | orgRole | OrganizationCustomRoleKey | undefined | The current user's Role in their Active OrganizationA user can be a member of multiple Organizations, but only one can be active at a time. The Active Organization determines which Organization-specific data the user can access and which Role and related Permissions they have within the Organization.. | | orgSlug | string | undefined | The URL-friendly identifier of the user's Active OrganizationA user can be a member of multiple Organizations, but only one can be active at a time. The Active Organization determines which Organization-specific data the user can access and which Role and related Permissions they have within the Organization.. | | sessionClaims | JwtPayload | The current user's session claims. | | sessionStatus | 'active' | 'pending' | The current state of the session. | | sessionId | string | The ID of the current session. | | tokenType | 'session\_token' | The type of request to authenticate. | | userId | string | The ID of the current user. | ### `has()` The `has()` helper can be used to do two types of checks: - **Authorization:** Check if the user has been granted a specific type of access control (Role, Permission, Feature, or Plan) and returns a boolean value. For examples, see the [guide on verifying if a user is authorized](https://clerk.com/docs/guides/secure/authorization-checks.md). - **Reverification:** Check if the user has verified their credentials within a certain time frame and returns a boolean value. For examples, see the [guide on reverification](https://clerk.com/docs/guides/secure/reverification.md). ```ts function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): boolean ``` #### `CheckAuthorizationParamsWithCustomPermissions` `CheckAuthorizationParamsWithCustomPermissions` has the following properties: | Name | Type | Description | | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | role | string | The Role to check for. | | permission | string | The Permission to check for. | | feature | string | The Feature to check for. | | plan | string | The Plan to check for. | | reverification? | ReverificationConfig | The reverification configuration to check for. This feature is currently in public beta. It is not recommended for production use. | ##### `ReverificationConfig` ```ts type ReverificationConfig = | SessionVerificationTypes | { level: SessionVerificationLevel afterMinutes: SessionVerificationAfterMinutes } type SessionVerificationTypes = 'strict_mfa' | 'strict' | 'moderate' | 'lax' ``` The `ReverificationConfig` type has the following properties: | Name | Type | Description | | ------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | strict\_mfa | | Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for both the first factorFirst factor is the first factor of authentication that is required to complete the authentication process. For example, when a user signs in with email and password, the password is the first factor. First factor verification is the process of verifying a user's identity using a single factor. This can be compared to second factor verificationSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor.., also known as two-factor authentication (2FA) or multi-factor authentication (MFA), where the user needs to provide an additional factor to verify their identity. and second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... | | strict | | Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for the second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... | | moderate | | Requires the user to verify their credentials within the past hour. If not verified, prompt for the second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... | | lax | | Requires the user to verify their credentials within the past day. If not verified, prompt for the second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... | | level | "first\_factor" | "second\_factor" | "multi\_factor" | The reverification level of credentials to check for. | | afterMinutes | number | The age of the factor level to check for. Value should be greater than or equal to 1 and less than 99,999. | ### `getToken()` `getToken()` retrieves the current user's [session token](https://clerk.com/docs/guides/sessions/session-tokens.md) or a [custom JWT template](https://clerk.com/docs/guides/sessions/jwt-templates.md). > Providing a `template` will perform a network request and will count towards [rate limits](https://clerk.com/docs/guides/how-clerk-works/system-limits.md#backend-api-requests). ```typescript const getToken: ServerGetToken type ServerGetToken = (options?: ServerGetTokenOptions) => Promise type ServerGetTokenOptions = { template?: string // The name of the custom JWT template to retrieve. } ``` #### Example: Use `getToken()` in the frontend The `Auth` object is not available in the frontend. To use the `getToken()` method in the frontend: - For React-based applications, you can use the `useAuth()` hook. See the [reference documentation](https://clerk.com/docs/reference/hooks/use-auth.md) for example usage. - For JavaScript applications, see the [reference documentation](https://clerk.com/docs/reference/objects/session.md#get-token) for example usage. #### Example: Use `getToken()` in the backend To use the `getToken()` method in the backend: - In App Router applications, use the [auth()](https://clerk.com/docs/reference/nextjs/app-router/auth.md) helper. - In Pages Router applications, use the [getAuth()](https://clerk.com/docs/reference/nextjs/pages-router/get-auth.md) helper. **App Router** filename: app/api/get-token-example/route.ts ```js import { auth } from '@clerk/nextjs/server' export async function GET() { const { getToken } = await auth() const template = 'test' const token = await getToken({ template }) return Response.json({ token }) } ``` **Pages Router** filename: pages/api/getToken.ts ```ts import { getAuth } from '@clerk/nextjs/server' import type { NextApiRequest, NextApiResponse } from 'next' export default async function handler(req: NextApiRequest, res: NextApiResponse) { const { getToken } = getAuth(req) const template = 'test' const token = await getToken({ template }) return res.json({ token }) } ``` ## `Auth` object example without Active Organization The following is an example of the `Auth` object without an Active Organization. Notice that there is no `o` claim. Read more about token claims in the [guide on session tokens](https://clerk.com/docs/guides/sessions/session-tokens.md). **Version 2** > This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above. ```js { azp: 'http://localhost:3000', email: 'email@example.com', exp: 1744735488, fva: [ 9, -1 ], iat: 1744735428, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', jti: 'aee4d4a5071bdd66e21b', nbf: 1744735418, pla: 'u:example-plan', role: 'authenticated', sid: 'sess_123', sub: 'user_123', v: 2 } ``` **Version 1** > Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the [**Updates**](https://dashboard.clerk.com/~/updates) page in the Clerk Dashboard. ```js { sessionId: 'sess_123', userId: 'user_123', orgId: null, orgRole: null, orgSlug: null, orgPermissions: null, has: [Function (anonymous)], getToken: [AsyncFunction (anonymous)], claims: { azp: 'http://localhost:3000', exp: 1666622607, iat: 1666622547, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', nbf: 1666622537, sid: 'sess_123', sub: 'user_123', }, } ``` ## `Auth` object example with Active Organization The following is an example of the `Auth` object with an Active Organization. Notice the addition of the `o` claim. Read more about token claims in the [guide on session tokens](https://clerk.com/docs/guides/sessions/session-tokens.md). **Version 2** > This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above. ```js { azp: 'http://localhost:3000', email: 'email@example.com', exp: 1744734948, fea: 'o:example-feature', fva: [ 0, -1 ], iat: 1744734888, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', jti: '004f0096e5cd44911924', nbf: 1744734878, o: { fpm: '1', id: 'org_123', per: 'example-perm', rol: 'admin', slg: 'example-org' }, pla: 'o:free_org', role: 'authenticated', sid: 'sess_123', sub: 'user_123', v: 2 } ``` **Version 1** > Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the [**Updates**](https://dashboard.clerk.com/~/updates) page in the Clerk Dashboard. ```js { sessionId: 'sess_123', userId: 'user_123', orgId: 'org_123', orgRole: 'org:admin', orgSlug: undefined, orgPermissions: ['org:example-feature:example-perm'], // Custom Permissions has: [Function (anonymous)], getToken: [AsyncFunction (anonymous)], claims: { azp: 'http://localhost:3000', exp: 1666622607, iat: 1666622547, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', nbf: 1666622537, sid: 'sess_123', sub: 'user_123', }, } ``` ## `Auth` object example with valid factor age The following is an example of the `Auth` object with a valid factor age. Notice the addition of the `fva` claim with a value of `[0, 0]`, indicating that the first factor and second factor have been verified within the past minute. Read more about token claims in the [guide on session tokens](https://clerk.com/docs/guides/sessions/session-tokens.md). **Version 2** > This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above. ```js { azp: 'http://localhost:3000', email: 'email@example.com', exp: 1744735488, fva: [ 0,0 ], iat: 1744735428, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', jti: 'aee4d4a5071bdd66e21b', nbf: 1744735418, role: 'authenticated', sid: 'sess_123', sub: 'user_123', v: 2 } ``` **Version 1** > Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the [**Updates**](https://dashboard.clerk.com/~/updates) page in the Clerk Dashboard. ```js { sessionId: 'sess_123', userId: 'user_123', orgId: null, orgRole: null, orgSlug: null, orgPermissions: null, factorVerificationAge: [0,0], has: [Function (anonymous)], getToken: [AsyncFunction (anonymous)], claims: { azp: 'http://localhost:3000', exp: 1666622607, iat: 1666622547, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', nbf: 1666622537, sid: 'sess_123', sub: 'user_123', }, } ``` ## `Auth` object example of a user without an MFA method registered The following is an example of the `Auth` object of a user without an MFA method registered. Notice the addition of the `fva` claim, but the value is `[0, -1]`. `0` indicates that the first factor has been verified within the past minute, and `-1` indicates that there is no second factor registered for the user. Read more about token claims in the [guide on session tokens](https://clerk.com/docs/guides/sessions/session-tokens.md). **Version 2** > This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above. ```js { azp: 'http://localhost:3000', email: 'email@example.com', exp: 1744735488, fva: [ 0,-1 ], iat: 1744735428, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', jti: 'aee4d4a5071bdd66e21b', nbf: 1744735418, role: 'authenticated', sid: 'sess_123', sub: 'user_123', v: 2 } ``` **Version 1** > Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the [**Updates**](https://dashboard.clerk.com/~/updates) page in the Clerk Dashboard. ```js { sessionId: 'sess_123', userId: 'user_123', orgId: null, orgRole: null, orgSlug: null, orgPermissions: null, factorVerificationAge: [0, -1], has: [Function (anonymous)], getToken: [AsyncFunction (anonymous)], claims: { azp: 'http://localhost:3000', exp: 1666622607, iat: 1666622547, iss: 'https://renewing-bobcat-00.clerk.accounts.dev', nbf: 1666622537, sid: 'sess_123', sub: 'user_123', }, } ``` ## Machine properties | Name | Type | Description | | ---------- | -------------------------------------------- | ----------------------------------------------------------------------- | | id | string | The ID of the machine. | | subject | string | The ID of the user or Organization that the machine is associated with. | | name | string | The name of the machine. For 'api\_key' and 'machine\_token' types. | | claims | Record | null | The machine's claims. For 'api\_key' and 'machine\_token' types. | | scopes | string[] | The scopes of the machine. | | getToken() | () => Promise | A function that gets the machine's token. | | tokenType | 'api\_key' | 'oauth\_token' | 'm2m\_token' | The type of request to authenticate. | | debug | AuthObjectDebug | Used to help debug issues when using Clerk in development. | ## `Auth` object example of a machine request The following is an example of the `Auth` object of an authenticated machine request (i.e. a request authenticated using a machine token like an API key). Notice the addition of a `tokenType` property with the value of `'api_key'`, which distinguishes the request as a machine request rather than a user session. The `scopes` array defines the permissions granted by the token. ```js { id: 'oat_123', tokenType: 'oauth_token', userId: 'user_123', clientId: 'client_123', name: 'GitHub OAuth', scopes: ['read', 'write'], getToken: [AsyncFunction (anonymous)], } ``` --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)