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.
Session 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
tokenType- Type
'session_token'- Description
The type of request to authenticate.
- 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. 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): booleanCheckAuthorizationParamsWithCustomPermissions
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.
getToken()
getToken() retrieves the current user's session token or a custom JWT template.
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:
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 })
}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 })
}import { getAuth } from '@clerk/tanstack-react-start/server'
import { json } from '@tanstack/react-start'
import { createServerFileRoute } from '@tanstack/react-start/server'
export const ServerRoute = createServerFileRoute().methods({
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.
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.
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.
{
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
}{
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.
{
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
}{
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.
{
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
}{
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.
{
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
}{
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',
},
}- Name
id- Type
string- Description
The ID of the machine.
- Name
subject- Type
string- Description
The ID of the user or organization that the machine is associated with.
- Name
name- Type
string- Description
The name of the machine. For 'api_key' and 'machine_token' types.
- Name
claims- Type
Record<string, unknown> | null- Description
The machine's claims. For 'api_key' and 'machine_token' types.
- Name
scopes- Type
string[]- Description
The scopes of the machine.
- Name
- getToken()
- Type
() => Promise<string>- Description
A function that gets the machine's token.
- Name
tokenType- Type
'api_key' | 'oauth_token' | 'machine_token'- Description
The type of request to authenticate.
- Name
debug- Type
AuthObjectDebug- Description
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.
{
id: 'oat_123',
tokenType: 'oauth_token',
userId: 'user_123',
clientId: 'client_123',
name: 'GitHub OAuth',
scopes: ['read', 'write'],
getToken: [AsyncFunction (anonymous)],
}Feedback
Last updated on