Skip to main content
Docs

getAuth()

The getAuth() helper retrieves authentication state from the request object. See the Next.js reference documentationNext.js Icon 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. Unlike requireAuth(), it can be used to protect API routes.

Quiz

When should you use getAuth() instead of requireAuth()?

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())

// 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}`)
})

Example: Protect a route based on authorization status

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 , 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`)
  }
})

getAuth() options

  • Name
    request
    Description

    The request object.

  • Name
    opts?
    Type
    {acceptsToken: TokenType, treatPendingAsSignedOut: boolean }
    Description

    An optional 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 statusJavaScript Icon as signed out. Defaults to true.

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on