Skip to main content
Docs
Dashboard

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.

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.

FrameworkHow to access the Auth object
Next.js App Routerauth()
Next.js Pages RoutergetAuth()
Astrolocals.auth()
Expressreq.auth
React RoutergetAuth()
RemixgetAuth()
Tanstack React StartgetAuth()
Otherrequest.auth

Properties

  • Name
    sessionId
    Type
    string
    Description

    The ID of the current session.

  • Name
    userId
    Type
    string
    Description

    The ID of the current user.

  • Name
    orgId
    Type
    string | undefined
    Description

    The ID of the user's active organization.

  • 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
    orgPermissions
    Type
    OrganizationCustomPermissionKey[] | undefined
    Description

    The current user's active organization permissions.

  • Name
    sessionClaims
    Type
    JwtPayload
    Description

    The current user's session claims.

  • Name
    actor
    Type
    ActClaim | undefined
    Description

    Holds identifier for the user that is impersonating the current user. Read more about impersonation.

  • Name
    has()
    Type
    (isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean
    Description

    A function that checks if the user has an organization role or custom permission.

  • Name
    factorVerificationAge
    Type
    [number, number] | null
    Description

    An array where each item represents the number of minutes since the last verification of a first 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
    debug
    Type
    AuthObjectDebug
    Description

    Used to help debug issues when using Clerk in development.

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.
  • Reverification: Check if the user has verified their credentials within a certain time frame and returns a boolean value.
function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): boolean

CheckAuthorizationParamsWithCustomPermissions

CheckAuthorizationParamsWithCustomPermissions has the following properties:

  • Name
    role
    Type
    string
    Description

    The role to check for.

  • Name
    permission
    Type
    string
    Description

    The permission to check for.

  • Name
    feature
    Type
    string
    Description

    The feature 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.

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

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

The ReverificationConfig type has the following properties:

  • Name
    strict_mfa
    Description

    Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for both the first and second factors.

  • Name
    strict
    Description

    Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for the second factor.

  • Name
    moderate
    Description

    Requires the user to verify their credentials within the past hour. If not verified, prompt for the second factor.

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

Examples

Authorization: For examples of how to use has() to check if a user has been granted a specific type of access control (role, permission, feature, or plan), see the guide on verifying if a user is authorized.

Reverification: For examples of how to use has() to check if a user has verified their credentials within a certain time frame, see the guide on reverification.

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 towards 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:

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/api/get-token-example/route.ts
import { auth } from '@clerk/nextjs/server'

export async function GET() {
  const { getToken } = await auth()

  const template = 'supabase'

  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 })
}
app/routes/api/example.ts
import { getAuth } from '@clerk/tanstack-react-start/server'
import { json } from '@tanstack/react-start'
import { createAPIFileRoute } from '@tanstack/react-start/api'

export const Route = createAPIFileRoute('/api/example')({
  GET: async ({ req, params }) => {
    const { userId, getToken } = await getAuth(req)

    if (!userId) {
      return json({ error: 'Unauthorized' }, { status: 401 })
    }

    const token = await getToken({ template: 'supabase' })

    // Add logic that retrieves the data
    // from your database using the token

    return json({
      // ...
    })
  },
})

To use the getToken() method in the backend, you can access it using the Auth object returned by the request object.

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

  const template = 'test'

  const token = await getToken({ template })

  res.json({ token })
})

To use the getToken() method in the backend, you can access it using the getAuth() function.

app/routes/get-token.ts
import { getAuth } from '@clerk/remix/ssr.server'
import { ActionFunction, json } from '@remix-run/node'

export const action: ActionFunction = async (req) => {
  const { getToken } = await getAuth(req)

  const template = 'test'

  const token = await getToken({ template })

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

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,
  role: 'authenticated',
  sid: 'sess_123',
  sub: 'user_123',
  v: 2
}

Important

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. Read more about token claims in the guide on session tokens.

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'
  },
  role: 'authenticated',
  sid: 'sess_123',
  sub: 'user_123',
  v: 2
}

Important

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 and second factors have been verified within the past minute. Read more about token claims in the guide on session tokens.

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
}

Important

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. Read more about token claims in the guide on session tokens.

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
}

Important

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',
    },
  }

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on