getAuth()
The getAuth() helper retrieves authentication state from the request object. See the Next.js reference documentation for more examples on how to use the returned auth object.
Usage
The getAuth() helper can be used to protect routes based on authentication status, authorization status, and token type. It also offers more granular control over how to handle unauthenticated users - you can redirect them to the sign-in page, return a 401 status code, or perform whatever action you need.
Example: Protect a route based on authentication status
The following example uses getAuth() to protect the route based on authentication status.
import { clerkMiddleware, getAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
// Apply `clerkMiddleware()` to all routes
app.use(clerkMiddleware())
app.get('/path', (req, res) => {
// Use `getAuth()` to protect a route based on authentication status
const auth = getAuth(req)
if (!auth.isAuthenticated) {
res.status(401).send('User not authenticated')
return
}
res.json(auth)
})
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`)
})Example: Protect a route based on authorization status
The following example uses getAuth() to protect the route based on authentication and authorization status.
import { clerkMiddleware, getAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
// Apply `clerkMiddleware()` to all routes
app.use(clerkMiddleware())
app.get('/path', (req, res) => {
// Use `getAuth()` to protect a route based on authorization status
const auth = getAuth(req)
// Handle if the user is not authenticated
if (!auth.isAuthenticated) {
res.status(401).send('Unauthorized')
return
}
// Handle if the user is authenticated but not authorized
if (!auth.has({ permission: 'org:admin:example' })) {
res.status(403).send('Forbidden')
return
}
res.json(auth)
})
// Start the server and listen on the specified port
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`)
})For more examples on how to use getAuth() to perform , see the dedicated guide.
Example: Protect a route based on token type
The following example uses getAuth() to protect the route based on token type:
- It accepts any token type
(acceptsToken: 'any')from the request. - If the token is a
session_token, it logs that the request is from a user session. - Otherwise, it logs that the request uses a machine token and specifies its type.
import express from 'express'
import { clerkMiddleware, getAuth } from '@clerk/express'
const app = express()
const PORT = 3000
// Apply `clerkMiddleware()` to all routes
app.use(clerkMiddleware())
app.get('/path', (req, res) => {
// Use `getAuth()` to protect a route based on token type
const authObject = getAuth(req, { acceptsToken: 'any' })
if (authObject.tokenType === 'session_token') {
console.log('This is a session token from a user')
} else {
console.log(`This is a ${authObject.tokenType} token`)
}
})- Name
request- Description
The request object.
- Name
opts?- Type
{acceptsToken: TokenType, treatPendingAsSignedOut: boolean }- Description
An object that can be used to configure the behavior of the
getAuth()function. It accepts the following properties:-
acceptsToken?: The type of authentication token(s) to accept. Valid values are:'session_token'- authenticates a user session.'oauth_token'- authenticates a machine request using OAuth.'m2m_token'- authenticates a machine to machine request.'api_key'- authenticates a machine request using API keys.
Can be set to:
- A single token type.
- An array of token types.
'any'to accept all available token types.
Defaults to
'session_token'. -
treatPendingAsSignedOut?: A boolean that indicates whether to treat pending session status as signed out. Defaults totrue.
-
Feedback
Last updated on