Custom API route prefix
An application needs Auth.js routes under a non-default URL prefix.
Auth.js · Pipe
basePath
basePath sets the URL prefix for Auth.js API endpoints. It defaults to /api/auth in Next.js and /auth in other integrations.
How it works
basePath changes the URL prefix used by Auth.js API endpoints. In Next.js, the default is /api/auth; other integrations default to /auth, so a custom value must also be reflected wherever Auth.js callback URLs are configured.
Syntax
basePath?: stringParameters
| Name | Type | Description |
|---|---|---|
basePath | string | Base path of the Auth.js API endpoints. |
Key points
- The configuration property is optional and accepts a string.
- It defines the shared URL prefix for Auth.js API endpoints.
- Next.js and non-Next.js integrations have different defaults.
Common mistakes
- It changes the endpoint prefix, not an individual endpoint name.
- The default differs between Next.js and other Auth.js integrations.
Example: Configure a custom Auth.js API path
import NextAuth from "next-auth"
export const { handlers, auth } = NextAuth({
basePath: "/custom-auth",
providers: [],
})Sets the Auth.js API endpoints under the custom /custom-auth path instead of the default Next.js path.
When to use it
OAuth callback configuration
An OAuth provider must redirect to an Auth.js callback beneath the configured route prefix.
Interview questions
QWhat does basePath configure, and what are its defaults?
basePath is an optional string configuration property that defines the base path for Auth.js API endpoints. Its default is /api/auth for next-auth and /auth for other frameworks.
Follow-up: What must be updated when using OAuth with a custom base path? Configure the provider callback URL using the custom path before /callback/{id}.
QHow do you configure a custom Auth.js base path?
Set basePath in the Auth.js configuration object, for example basePath: "/custom-auth". This makes Auth.js use that prefix for its API routes.
Follow-up: How would you verify the resulting route? Check that the generated Auth.js endpoints are served beneath the configured prefix rather than the framework default.
QHow does basePath affect OAuth callback URLs?
For OAuth, the callback URL incorporates the configured base path in the form https://app.com/{basePath}/callback/{id}. Therefore, a custom base path must be represented in the provider dashboard callback configuration.
Follow-up: Why can an unchanged provider callback URL break sign-in? The provider redirects to the old endpoint prefix, so Auth.js does not receive the OAuth callback at the configured route.
Related
AuthConfigcallback URLAuth.js API endpoints