Auth object

How to access the Auth object
Session properties
1. has()
2. getToken()
Auth object example without Active Organization
Auth object example with Active Organization
Auth object example with valid factor age
Auth object example of a user without an MFA method registered
Machine properties
Auth object example of a machine request

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.

Note

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 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()
Next.js Pages Router	getAuth()
Astro	locals.auth()
Express	`req.auth`
Fastify	getAuth()
Nuxt	event.context.auth()
React Router	getAuth()
TanStack React Start	auth()
Other	`request.auth`

Session properties

Name
actor
Type
ActClaim | undefined
Description
Holds identifier for the user that is impersonating the current user. Read more about impersonation.
Name
debug
Type
AuthObjectDebug
Description
Used to help debug issues when using Clerk in development.
Name
factorVerificationAge
Type
[number, number] | null
Description
An array where each item represents the number of minutes since the last verification of a first factor or second factor: [firstFactorAge, secondFactorAge].
Name
getToken()
Type
ServerGetToken
Description
A function that gets the current user's session token or a custom JWT template.
Name
has()
Type
(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean
Description
A function that checks if the user has an Organization Role or custom Permission.
Name
orgId
Type
string | undefined
Description
The ID of the user's Active Organization.
Name
orgPermissions
Type
OrganizationCustomPermissionKey[] | undefined
Description
The current user's Active Organization permissions.
Name
orgRole
Type
OrganizationCustomRoleKey | undefined
Description
The current user's Role in their Active Organization.
Name
orgSlug
Type
string | undefined
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 of the current session.
Name
sessionStatus
Type
'active' | 'pending'
Description
The current state of the session.
Name
tokenType
Type
'session_token'
Description
The type of request to authenticate.
Name
userId
Type
string
Description
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.
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.

function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): boolean

`CheckAuthorizationParamsWithCustomPermissions`

CheckAuthorizationParamsWithCustomPermissions has the following properties:

Name
feature
Type
string
Description
The Feature to check for.
Name
permission
Type
string
Description
The Permission to check for.
Name
plan
Type
string
Description
The Plan to check for.
Name
reverification?
Type
ReverificationConfig
Description
The reverification configuration to check for. This feature is currently in public beta. It is not recommended for production use.
Name
role
Type
string
Description
The Role to check for.

`ReverificationConfig`

type ReverificationConfig =
  | SessionVerificationTypes
  | {
      level: SessionVerificationLevel
      afterMinutes: SessionVerificationAfterMinutes
    }

type SessionVerificationTypes = 'strict_mfa' | 'strict' | 'moderate' | 'lax'

The ReverificationConfig type has the following properties:

Name
afterMinutes
Type
number
Description
The age of the factor level to check for. Value should be greater than or equal to 1 and less than 99,999.
Name
lax
Description
Requires the user to verify their credentials within the past day. If not verified, prompt for the second factor.
Name
level
Type
"first_factor" | "second_factor" | "multi_factor"
Description
The reverification level of credentials to check for.
Name
moderate
Description
Requires the user to verify their credentials within the past hour. If not verified, prompt for the second factor.
Name
strict
Description
Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for the second factor.
Name
strict_mfa
Description
Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for both the first factor and second factor.

`getToken()`

getToken() retrieves the current user's session token or a custom JWT template.

Note

Providing a template will perform a network request and will count toward rate limits.

const getToken: ServerGetToken

type ServerGetToken = (options?: ServerGetTokenOptions) => Promise<string | null>

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 for example usage.
For JavaScript applications, see the reference documentation for example usage.

Example: Use `getToken()` in the backend

To use the getToken() method in the backend:

In App Router applications, use the auth() helper.
In Pages Router applications, use the getAuth() helper.

App Router

Pages Router

app/api/get-token-example/route.ts

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/api/getToken.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 })
}

src/pages/api/example.ts

import type { APIRoute } from 'astro'

export const GET: APIRoute = async (context) => {
  const { getToken } = context.locals.auth()

  const template = 'test'

  const token = await getToken({ template })

  return context.json({ token })
}

getToken.ts

app.get('/api/get-token', async (req, res) => {
  const { getToken } = req.auth

  const template = 'test'

  const token = await getToken({ template })

  res.json({ token })
})

src/routes/example.ts

import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
import { getAuth } from '@clerk/fastify'

export const exampleRoutes = (fastify: FastifyInstance) => {
  fastify.get('/example', async (req: FastifyRequest, res: FastifyReply) => {
    const { getToken } = getAuth(req)

    const template = 'test'

    const token = await getToken({ template })

    return res.json({ token })
  })
}

server/api/example.ts

export default defineEventHandler(async (event) => {
  const { getToken } = event.context.auth()

  const template = 'test'

  const token = await getToken({ template })

  return { token }
})

app/routes/example.tsx

import { getAuth } from '@clerk/react-router/server'
import type { Route } from './+types/example'

export async function loader(args: Route.LoaderArgs) {
  const { getToken } = await getAuth(args)

  const template = 'test'

  const token = await getToken({ template })

  return { token }
}

src/routes/api/example.ts

import { auth } from '@clerk/tanstack-react-start/server'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/example')({
  server: {
    handlers: {
      GET: async () => {
        const { getToken } = await auth()

        const template = 'test'

        const token = await getToken({ template })

        return Response.json({ token })
      },
    },
  },
})

Use request.auth to access the Auth object.

export async function GET(request: Request) {
  const { getToken } = request.auth

  const template = 'test'

  const token = await getToken({ template })

  return Response.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.

Version 2

Version 1

Important

This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above.

{
  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
}

Deprecated

Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the Updates page in the Clerk Dashboard.

{
  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.

Version 2

Version 1

Important

This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above.

{
  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
}

Deprecated

Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the Updates page in the Clerk Dashboard.

{
  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.

Version 2

Version 1

Important

This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above.

{
  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
}

Deprecated

Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the Updates page in the Clerk Dashboard.

{
  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.

Version 2

Version 1

Important

This example is for version 2 of Clerk's session token. To see an example of version 1, select the respective tab above.

{
  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
}

Deprecated

Version 1 of Clerk's session token was deprecated on April 14, 2025. To upgrade to version 2, go to the Updates page in the Clerk Dashboard.

{
  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
claims
Type
Record<string, unknown> | null
Description
The machine's claims. For 'api_key' and 'machine_token' types.
Name
debug
Type
AuthObjectDebug
Description
Used to help debug issues when using Clerk in development.
Name
getToken()
Type
() => Promise<string>
Description
A function that gets the machine's token.
Name
id
Type
string
Description
The ID of the machine.
Name
name
Type
string
Description
The name of the machine. For 'api_key' and 'machine_token' types.
Name
scopes
Type
string[]
Description
The scopes of the machine.
Name
subject
Type
string
Description
The ID of the user or Organization that the machine is associated with.
Name
tokenType
Type
'api_key' | 'oauth_token' | 'm2m_token'
Description
The type of request to authenticate.

`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.

{
  id: 'oat_123',
  tokenType: 'oauth_token',
  userId: 'user_123',
  clientId: 'client_123',
  name: 'GitHub OAuth',
  scopes: ['read', 'write'],
  getToken: [AsyncFunction (anonymous)],
}

Last updated on Nov 7, 2026

Edit on GitHub

Auth object

ReverificationConfig

Feedback

`ReverificationConfig`