Stack Auth provides specialized app classes for Next.js server and client environments.
StackServerApp
The StackServerApp class provides server-side authentication with access to user management APIs.
Constructor Options
Token storage mechanism. Use "nextjs-cookie" for Next.js applications.
Your Stack Auth project ID. Defaults to NEXT_PUBLIC_STACK_PROJECT_ID environment variable.
Your publishable client key. Defaults to NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY.
Your secret server key. Defaults to STACK_SECRET_SERVER_KEY environment variable.
Custom URL configuration for authentication pages.
signIn
string
default:"/handler/sign-in"
Sign in page URL
signUp
string
default:"/handler/sign-up"
Sign up page URL
accountSettings
string
default:"/handler/account-settings"
Account settings page URL
Redirect URL after successful sign in
Redirect URL after successful sign up
Redirect URL after sign out
Example
// stack.ts
import "server-only";
import { StackServerApp } from "@stackframe/stack";
export const stackServerApp = new StackServerApp({
tokenStore: "nextjs-cookie",
urls: {
accountSettings: '/settings',
afterSignIn: '/dashboard',
afterSignUp: '/onboarding',
}
});
Core Methods
getUser()
Retrieve the current authenticated user on the server.
// app/page.tsx
import { stackServerApp } from './stack';
export default async function Page() {
const user = await stackServerApp.getUser();
if (!user) {
return <div>Not signed in</div>;
}
return <div>Welcome, {user.displayName}!</div>;
}
or
'redirect' | 'throw' | 'anonymous'
Behavior when user is not authenticated:
'redirect': Redirect to sign in page'throw': Throw an error'anonymous': Return anonymous user
Override default token store
Promise<CurrentServerUser | null>
createUser()
Create a new user programmatically.
const newUser = await stackServerApp.createUser({
primaryEmail: '[email protected]',
password: 'secure_password',
displayName: 'John Doe',
});
User’s primary email address
User’s password (if using credential authentication)
URL to user’s profile image
Promise<ServerUser>
listUsers()
List all users in the project.
const users = await stackServerApp.listUsers({
limit: 50,
orderBy: 'createdAt',
});
console.log(`Found ${users.length} users`);
console.log(`Next cursor: ${users.nextCursor}`);
Maximum number of users to return
Pagination cursor from previous response
orderBy
'createdAt' | 'signedUpAt'
default:"'createdAt'"
Field to sort by
Promise<ServerUser[] & { nextCursor: string | null }>
createTeam()
Create a new team.
const team = await stackServerApp.createTeam({
displayName: 'Engineering Team',
});
Promise<ServerTeam>
sendEmail()
Send a custom email using Stack Auth’s email service.
await stackServerApp.sendEmail({
to: '[email protected]',
subject: 'Welcome!',
html: '<p>Welcome to our app!</p>',
});
HTML content of the email
Promise<void>
StackClientApp
For client-side usage in React components, see the React SDK documentation.
StackAdminApp
The StackAdminApp extends StackServerApp with full administrative capabilities.
Constructor Options
Includes all StackServerApp options plus:
Your super secret admin key. Defaults to STACK_SUPER_SECRET_ADMIN_KEY environment variable.
Example
import "server-only";
import { StackAdminApp } from "@stackframe/stack";
export const stackAdminApp = new StackAdminApp({
tokenStore: "nextjs-cookie",
superSecretAdminKey: process.env.STACK_SUPER_SECRET_ADMIN_KEY,
});
Admin Methods
Additional methods available on StackAdminApp:
createInternalApiKey() - Create API keyscreateTeamPermissionDefinition() - Define team permissionscreateProjectPermissionDefinition() - Define project permissionssendTestEmail() - Send test emailslistSentEmails() - View email historyqueryAnalytics() - Query analytics data
See the API Reference for complete documentation.