Skip to main content
Docs

Route Handlers

Clerk provides helpers that allow you to protect your Route Handlers, fetch the current user, and interact with the Clerk Backend API.

Tip

If you have a <Link> tag on a public page that points to a protected page that returns a 400-level error, like a 401, the data prefetch will fail because it will be redirected to the sign-in page and throw a confusing error in the console. To prevent this behavior, disable prefetching by adding prefetch={false} to the <Link> component.

Protect your Route Handlers

If you aren't protecting your Route Handler using , you can protect your Route Handler in two ways:

  • Use if you want Clerk to return a 404 error when there is no signed in user.
  • Use if you want to customize the behavior or error message.
app/api/route.ts
import { auth } from '@clerk/nextjs/server'

export async function GET() {
  // If there is no signed in user, this will return a 404 error
  await auth.protect()

  // Add your Route Handler logic here

  return Response.json({ message: 'Hello world!' })
}
app/api/route.ts
import { auth } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'

export async function GET() {
  const { userId } = await auth()

  if (!userId) {
    return NextResponse.json({ error: 'Error: No signed in user' }, { status: 401 })
  }

  // Add your Route Handler logic here

  return NextResponse.json({ userId })
}

Retrieve data from external sources

Clerk provides integrations with a number of popular databases.

The following example demonstrates how to use to retrieve a token from a JWT template and use it to fetch data from the external source.

app/api/route.ts
import { NextResponse } from 'next/server'
import { auth } from '@clerk/nextjs/server'
export async function GET() {
  const { userId, getToken } = await auth()

  if (!userId) {
    return new Response('Unauthorized', { status: 401 })
  }

  const token = await getToken({ template: 'supabase' })

  // Fetch data from Supabase and return it.
  const data = { supabaseData: 'Hello World' }

  return NextResponse.json({ data })
}

Retrieve the current user

To retrieve information about the current user in your Route Handler, you can use the helper, which returns the object of the currently active user. It does count towards the Backend API request rate limit so it's recommended to use the useUser() hook on the client side when possible and only use currentUser() when you specifically need user data in a server context. For more information on this helper, see the reference.

app/api/route.ts
import { NextResponse } from 'next/server'
import { currentUser } from '@clerk/nextjs/server'
export async function GET() {
  const user = await currentUser()

  if (!user) {
    return new Response('Unauthorized', { status: 401 })
  }

  return NextResponse.json({ user })
}

Interact with Clerk's Backend API

The exposes the Backend API resources and low-level authentication utilities for JavaScript environments.

clerkClient exposes an instance of the JavaScript Backend SDK for use in server environments.

app/api/route.ts
import { NextResponse, NextRequest } from 'next/server'
import { auth, clerkClient } from '@clerk/nextjs/server'

export async function POST(req: NextRequest) {
  const { userId } = await auth()

  if (!userId) return NextResponse.redirect(new URL('/sign-in', req.url))

  const params = { firstName: 'John', lastName: 'Wick' }

  const client = await clerkClient()

  const user = await client.users.updateUser(userId, params)

  return NextResponse.json({ user })
}

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on