# getAuth()

The `getAuth()` helper retrieves authentication state from the `request` object. See the [Next.js reference documentation](https://clerk.com/docs/reference/nextjs/pages-router/get-auth.md) 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()`](https://clerk.com/docs/reference/express/require-auth.md), it **can** be used to protect API routes.

> [!QUIZ]
> When should you use `getAuth()` instead of [`requireAuth()`](https://clerk.com/docs/reference/express/require-auth.md)?
>
> ***
>
> The [`requireAuth()`](https://clerk.com/docs/reference/express/require-auth.md) 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. The `getAuth()` helper offers more options for protecting routes, more granular control over how to protect them, and can be used to protect API routes.

### Example: Protect a route based on authentication status

The following example uses `getAuth()` to protect the route based on _authentication_ status.

```js
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()`](https://clerk.com/docs/reference/express/require-auth.md) 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()`.

```js
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](https://clerk.com/docs/guides/secure/authorization-checks.md).

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

```js
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                                                                            | Type                                                                                                                        | Description         |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| request                                                                         |                                                                                                                             | The request object. |
| acceptsToken?: The type of authentication token(s) to accept. Valid values are: | treatPendingAsSignedOut?: A boolean that indicates whether to treat pending session status as signed out. Defaults to true. |                     |

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)