You are currently viewing documentation for the canary channel of Next.js.

unauthorized

This API is currently in the canary channel and not yet available in a stable version.

The unauthorized function throws an error that renders a Next.js 401 error page. It's useful for handling authorization errors in your application. You can customize the UI using the unauthorized.js file.

To start using unauthorized, enable the experimental authInterrupts configuration option in your next.config.js file:

next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}
 
export default nextConfig

unauthorized can be invoked in Server Components, Server Actions, and Route Handlers.

app/dashboard/page.tsx

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export default async function DashboardPage() {
  const session = await verifySession()
 
  if (!session) {
    unauthorized()
  }
 
  // Render the dashboard for authenticated users
  return (
    <main>
      <h1>Welcome to the Dashboard</h1>
      <p>Hi, {session.user.name}.</p>
    </main>
  )
}

Good to know

The unauthorized function cannot be called in the root layout.

Examples

You can use unauthorized function to display the unauthorized.js file with a login UI.

app/dashboard/page.tsx

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export default async function DashboardPage() {
  const session = await verifySession()
 
  if (!session) {
    unauthorized()
  }
 
  return <div>Dashboard</div>
}

app/unauthorized.tsx

import Login from '@/app/components/Login'
 
export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>Please log in to access this page.</p>
      <Login />
    </main>
  )
}

Mutations with Server Actions

You can invoke unauthorized in Server Actions to ensure only authenticated users can perform specific mutations.

app/actions/update-profile.ts

'use server'
 
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
import db from '@/app/lib/db'
 
export async function updateProfile(data: FormData) {
  const session = await verifySession()
 
  // If the user is not authenticated, return a 401
  if (!session) {
    unauthorized()
  }
 
  // Proceed with mutation
  // ...
}

Fetching data with Route Handlers

You can use unauthorized in Route Handlers to ensure only authenticated users can access the endpoint.

app/api/profile/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export async function GET(req: NextRequest): Promise<NextResponse> {
  // Verify the user's session
  const session = await verifySession()
 
  // If no session exists, return a 401 and render unauthorized.tsx
  if (!session) {
    unauthorized()
  }
 
  // Fetch data
  // ...
}

Version History

Version	Changes
`v15.1.0`	`unauthorized` introduced.

unauthorized

Good to know

Examples

Displaying login UI to unauthenticated users

Mutations with Server Actions

Fetching data with Route Handlers

Version History

Next Steps

unauthorized.js