0
# Core Authentication Configuration
1

2
Core NextAuth configuration and request handling functionality. The central component for setting up authentication providers, callbacks, and session management in Next.js applications.
3

4
## Capabilities
5

6
### NextAuth Function
7

8
Main entry point for NextAuth configuration with multiple overloads for different Next.js routing patterns.
9

10
```typescript { .api }
11
/**
12
 * Configure NextAuth.js for authentication handling
13
 * @param options - Authentication configuration options
14
 * @returns Authentication handler function or response
15
 */
16
function NextAuth(options: AuthOptions): any;
17
function NextAuth(req: NextApiRequest, res: NextApiResponse, options: AuthOptions): any;
18
function NextAuth(req: NextRequest, res: RouteHandlerContext, options: AuthOptions): any;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
// App Router (app/api/auth/[...nextauth]/route.ts)
25
import NextAuth from "next-auth";
26
import GoogleProvider from "next-auth/providers/google";
27

28
const handler = NextAuth({
29
  providers: [
30
    GoogleProvider({
31
      clientId: process.env.GOOGLE_CLIENT_ID!,
32
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
33
    }),
34
  ],
35
});
36

37
export { handler as GET, handler as POST };
38

39
// Pages API (pages/api/auth/[...nextauth].ts)
40
import NextAuth from "next-auth";
41
import GoogleProvider from "next-auth/providers/google";
42

43
export default NextAuth({
44
  providers: [
45
    GoogleProvider({
46
      clientId: process.env.GOOGLE_CLIENT_ID!,
47
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
48
    }),
49
  ],
50
});
51
```
52

53
### AuthOptions Configuration
54

55
Main configuration interface containing all NextAuth.js options.
56

57
```typescript { .api }
58
/**
59
 * Complete configuration interface for NextAuth.js
60
 */
61
interface AuthOptions {
62
  /** Array of authentication providers for signing in */
63
  providers: Provider[];
64
  /** Random string used to hash tokens, sign cookies and generate cryptographic keys */
65
  secret?: string;  
66
  /** Session configuration options */
67
  session?: Partial<SessionOptions>;
68
  /** JWT configuration options */
69
  jwt?: Partial<JWTOptions>;
70
  /** URLs for custom pages */
71
  pages?: Partial<PagesOptions>;
72
  /** Lifecycle callback functions */
73
  callbacks?: Partial<CallbacksOptions>;
74
  /** Event handler functions */
75
  events?: Partial<EventCallbacks>;
76
  /** Database adapter for session and user management */
77
  adapter?: Adapter;
78
  /** Enable debug messages */
79
  debug?: boolean;
80
  /** Custom logger implementation */
81
  logger?: Partial<LoggerInstance>;
82
  /** UI theme configuration */
83
  theme?: Theme;
84
  /** Force secure cookies (HTTPS only) */
85
  useSecureCookies?: boolean;
86
  /** Custom cookie options */
87
  cookies?: Partial<CookiesOptions>;
88
}
89
```
90

91
### Session Configuration
92

93
Options for configuring session behavior and storage strategy.
94

95
```typescript { .api }
96
/**
97
 * Session configuration options
98
 */
99
interface SessionOptions {
100
  /** Session storage strategy - "jwt" for stateless, "database" for server-side storage */
101
  strategy: "jwt" | "database";
102
  /** Maximum session age in seconds (default: 30 days) */
103
  maxAge: number;
104
  /** How frequently to update session expiry in seconds (default: 24 hours) */
105
  updateAge: number;
106
  /** Custom session token generator function */
107
  generateSessionToken?: () => Awaitable<string>;
108
}
109
```
110

111
### JWT Configuration
112

113
Options for configuring JWT token behavior and encryption.
114

115
```typescript { .api }
116
/**
117
 * JWT configuration options
118
 */
119
interface JWTOptions {
120
  /** Secret used for JWT signing and encryption */
121
  secret: string;
122
  /** Maximum JWT age in seconds */
123
  maxAge: number;
124
  /** Custom JWT encoding function */
125
  encode?: (params: JWTEncodeParams) => Awaitable<string>;
126
  /** Custom JWT decoding function */
127
  decode?: (params: JWTDecodeParams) => Awaitable<JWT | null>;
128
}
129

130
interface JWTEncodeParams {
131
  /** JWT payload to encode */
132
  token?: JWT;
133
  /** Secret for encryption */
134
  secret: string;
135
  /** Maximum age in seconds */
136
  maxAge?: number;
137
  /** Salt for key derivation */
138
  salt?: string;
139
}
140

141
interface JWTDecodeParams {
142
  /** JWT token string to decode */
143
  token?: string;
144
  /** Secret for decryption */
145
  secret: string;
146
  /** Salt for key derivation */
147
  salt?: string;
148
}
149
```
150

151
### Custom Pages Configuration
152

153
URLs for custom authentication pages to override default NextAuth.js UI.
154

155
```typescript { .api }
156
/**
157
 * Custom page URLs configuration
158
 */
159
interface PagesOptions {
160
  /** Custom sign in page URL */
161
  signIn?: string;
162
  /** Custom sign out page URL */
163
  signOut?: string;
164
  /** Custom error page URL */
165
  error?: string;
166
  /** Custom email verification page URL */
167
  verifyRequest?: string;
168
  /** Custom new user registration page URL */
169
  newUser?: string;
170
}
171
```
172

173
**Usage Example:**
174

175
```typescript
176
export default NextAuth({
177
  providers: [...],
178
  pages: {
179
    signIn: '/auth/signin',
180
    signOut: '/auth/signout',
181
    error: '/auth/error',
182
  },
183
});
184
```
185

186
### Callbacks Configuration
187

188
Lifecycle callback functions for customizing authentication flow behavior.
189

190
```typescript { .api }
191
/**
192
 * Callback functions for customizing authentication flow
193
 */
194
interface CallbacksOptions<P = Profile, A = Account> {
195
  /** Control whether user is allowed to sign in */
196
  signIn?: (params: {
197
    user: User | AdapterUser;
198
    account: A | null;
199
    profile?: P;
200
    email?: { verificationRequest?: boolean };
201
    credentials?: Record<string, CredentialInput>;
202
  }) => Awaitable<string | boolean>;
203
  
204
  /** Control where user is redirected after authentication */
205
  redirect?: (params: {
206
    url: string;
207
    baseUrl: string;
208
  }) => Awaitable<string>;
209
  
210
  /** Customize session object sent to client */
211
  session?: (params: {
212
    session: Session;
213
    token: JWT;
214
    user: AdapterUser;
215
    newSession?: any;
216
    trigger?: "update";
217
  }) => Awaitable<Session | DefaultSession>;
218
  
219
  /** Customize JWT token contents */
220
  jwt?: (params: {
221
    token: JWT;
222
    user: User | AdapterUser;
223
    account: A | null;
224
    profile?: P;
225
    trigger?: "signIn" | "signUp" | "update";
226
    isNewUser?: boolean;
227
    session?: any;
228
  }) => Awaitable<JWT>;
229
}
230
```
231

232
**Usage Example:**
233

234
```typescript
235
export default NextAuth({
236
  providers: [...],
237
  callbacks: {
238
    async signIn({ user, account, profile }) {
239
      // Allow sign in only for specific email domains
240
      if (account?.provider === "google") {
241
        return user.email?.endsWith("@company.com") ?? false;
242
      }
243
      return true;
244
    },
245
    async session({ session, token }) {
246
      // Add user ID to session
247
      session.user.id = token.sub;
248
      return session;
249
    },
250
    async jwt({ token, user, account, profile }) {
251
      // Add account type to token on first sign in
252
      if (account) {
253
        token.accountType = account.type;
254
      }
255
      return token;
256
    },
257
  },
258
});
259
```
260

261
### Event Handlers
262

263
Event handler functions for logging and monitoring authentication events.
264

265
```typescript { .api }
266
/**
267
 * Event handler functions for authentication lifecycle events
268
 */
269
interface EventCallbacks {
270
  /** Triggered when user signs in */
271
  signIn?: (message: { user: User; account: Account | null; profile?: Profile; isNewUser?: boolean }) => Awaitable<void>;
272
  /** Triggered when user signs out */
273
  signOut?: (message: { session: Session; token: JWT }) => Awaitable<void>;
274
  /** Triggered when new user is created */
275
  createUser?: (message: { user: User }) => Awaitable<void>;
276
  /** Triggered when user profile is updated */
277
  updateUser?: (message: { user: User }) => Awaitable<void>;
278
  /** Triggered when provider account is linked */
279
  linkAccount?: (message: { user: User; account: Account; profile: Profile }) => Awaitable<void>;
280
  /** Triggered when session is accessed */
281
  session?: (message: { session: Session; token: JWT }) => Awaitable<void>;
282
}
283
```
284

285
### Cookie Configuration
286

287
Advanced cookie configuration options for customizing NextAuth.js cookie behavior.
288

289
```typescript { .api }
290
/**
291
 * Cookie configuration options
292
 */
293
interface CookiesOptions {
294
  sessionToken?: CookieOption;
295
  callbackUrl?: CookieOption;
296
  csrfToken?: CookieOption;
297
  pkceCodeVerifier?: CookieOption;
298
  state?: CookieOption;
299
  nonce?: CookieOption;
300
}
301

302
interface CookieOption {
303
  name: string;
304
  options: CookieSerializeOptions;
305
}
306
```
307

308
### Theme Configuration
309

310
UI theming options for customizing the appearance of built-in NextAuth.js pages.
311

312
```typescript { .api }
313
/**
314
 * Theme configuration for NextAuth.js UI
315
 */
316
interface Theme {
317
  colorScheme?: "light" | "dark" | "auto";
318
  logo?: string;
319
  brandColor?: string;
320
  buttonText?: string;
321
}
322
```
323

324
**Usage Example:**
325

326
```typescript
327
export default NextAuth({
328
  providers: [...],
329
  theme: {
330
    colorScheme: "dark",
331
    brandColor: "#1976d2",
332
    logo: "https://example.com/logo.png",
333
    buttonText: "#ffffff",
334
  },
335
});
336
```
337

338
## Types
339

340
### Core Data Types
341

342
```typescript { .api }
343
interface User extends DefaultUser {
344
  id: string;
345
  name?: string | null;
346
  email?: string | null;
347
  image?: string | null;
348
}
349

350
interface DefaultUser {
351
  id: string;
352
  name?: string | null;
353
  email?: string | null;
354
  image?: string | null;
355
}
356

357
interface Account extends Partial<TokenSetParameters> {
358
  providerAccountId: string;
359
  userId?: string;
360
  provider: string;
361
  type: ProviderType;
362
  access_token?: string;
363
  refresh_token?: string;
364
  expires_at?: number;
365
  token_type?: string;
366
  scope?: string;
367
  id_token?: string;
368
  session_state?: string;
369
}
370

371
interface Profile extends Record<string, any> {
372
  sub?: string;
373
  name?: string;
374
  email?: string;
375
  image?: string;
376
}
377

378
type Awaitable<T> = T | PromiseLike<T>;
379
type ISODateString = string;
380
```