āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/express/get-auth ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
getAuth()'
description: The getAuth() helper retrieves authentication state from the request object.
sdk: expressjsThe 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.
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. Unlike requireAuth(), it can be used to protect API routes.
[!QUIZ] When should you use
getAuth()instead ofrequireAuth()?
The
requireAuth()helper protects a route based on authentication status, and redirects unauthenticated users to the sign-in page. It can only be used in full-stack applications, and cannot be used to protect API routes. ThegetAuth()helper offers more options for protecting routes, more granular control over how to protect them, and can be used to protect API routes.
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())
// Use `getAuth()` to protect a route based on authentication status
app.get('/path', (req, res) => {
const auth = getAuth(req)
if (!auth.isAuthenticated) {
return res.status(401).send('User not authenticated')
}
return res.json(auth)
})
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`)
})
The following example demonstrates how to use requireAuth() and getAuth() together. requireAuth() protects the route based on authentication status while getAuth() protects the route based on authorization status. It also demonstrates how to use both clerkMiddleware() and requireAuth() together, as clerkMiddleware() will provide authentication state to routes that don't use requireAuth().
import { clerkMiddleware, getAuth, requireAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
// Apply `clerkMiddleware()` to all routes
app.use(clerkMiddleware())
// Use `getAuth()` to protect a route based on authorization status
const hasPermission = (req, res, next) => {
const auth = getAuth(req)
// Handle if the user is not authorized
if (!auth.has({ permission: 'org:admin:example' })) {
return res.status(403).send('Forbidden')
}
return next()
}
// Use `requireAuth()` to protect a route based on authentication status
// If user is not authenticated, requireAuth() will redirect back to the homepage
// Then, use the `hasPermission` function created above to protect the route based on authorization status
app.get('/path', requireAuth(), hasPermission, (req, res) => res.json(req.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 authorization checks, see the dedicated guide.
The following example uses getAuth() to protect the route based on token type:
(acceptsToken: 'any') from the request.session_token, it logs that the request is from a user session.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`)
}
})
getAuth() optionsThe request object.
opts?{acceptsToken: TokenType, treatPendingAsSignedOut: boolean }An optional object that can be used to configure the behavior of the getAuth() function. It accepts the following properties:
treatPendingAsSignedOut?: A boolean that indicates whether to treat pending session status as signed out. Defaults to true.
</Properties>
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā