StackServerApp is the main object for interacting with Stack Auth on the server. It provides methods for authentication, user management, and team management with full server permissions.

Note: Only use StackServerApp in trusted server environments. It requires your SECRET_SERVER_KEY.

Table of Contents

type StackServerApp = {
new(options): StackServerApp;

getUser([id], [options]): Promise<ServerUser|null>;
⤷ useUser([id], [options]): ServerUser;
listUsers([options]): Promise<ServerUser[]>;
⤷ useUsers([options]): ServerUser[];
createUser([options]): Promise<ServerUser>;

getTeam(id): Promise<ServerTeam|null>;
⤷ useTeam(id): ServerTeam;
listTeams(): Promise<ServerTeam[]>;
⤷ useTeams(): ServerTeam[];
createTeam([options]): Promise<ServerTeam>;
};

Constructor

Creates a new StackServerApp instance.

Parameters

  • tokenStore: The token store to use. Can be one of:
    • "nextjs-cookie": Uses Next.js cookies (recommended for Next.js apps)
    • "cookie": Uses browser cookies
    • { accessToken: string, refreshToken: string }: Uses provided tokens
    • Request: Uses the provided request object
  • secretServerKey: The secret server key for your app.
  • baseUrl, projectId, publishableClientKey, urls, noAutomaticPrefetch: (see StackClientApp for details)

Signature

declare new(options: {
  tokenStore: "nextjs-cookie" | "cookie" | { accessToken: string, refreshToken: string } | Request;
  secretServerKey?: string;
  baseUrl?: string;
  projectId?: string;
  publishableClientKey?: string;
  urls: { signIn: string; signUp?: string; forgotPassword?: string; };
  noAutomaticPrefetch?: boolean;
}): StackServerApp;

Example

const stackServerApp = new StackServerApp({
  tokenStore: 'nextjs-cookie',
  secretServerKey: process.env.SECRET_SERVER_KEY,
  urls: { signIn: '/my-custom-sign-in-page' },
});

Methods

stackServerApp.getUser([id], [options])

Returns a ServerUser by ID, or the current user if no ID is provided.

Parameters

  • id (string, optional): The user ID.
  • options (object, optional): { or?: "return-null" | "redirect" | "throw" }

Returns

Promise<ServerUser | null>

Example 

const user = await stackServerApp.getUser('user_id');

stackServerApp.useUser([id], [options])

Functionally equivalent to getUser([id], [options]), but as a React hook.

Parameters

  • id (string, optional): The user ID.
  • options (object, optional): { or?: "return-null" | "redirect" | "throw" }

Returns

ServerUser

Example 

const user = await stackServerApp.useUser('user_id');

stackServerApp.listUsers([options])

Lists all users on the project.

Parameters

  • options (object, optional):
    • cursor (string): The cursor to start from.
    • limit (number): Max number of users to return.
    • orderBy (string): Field to sort by ("signedUpAt").
    • desc (boolean): Sort descending.
    • query (string): Free-text search.

Returns

Promise<ServerUser[]> (with nextCursor property)

Example 

const users = await stackServerApp.listUsers({ limit: 20 });

stackServerApp.useUsers([options])

Functionally equivalent to listUsers([options]), but as a React hook.

Parameters

  • options (object, optional):
    • cursor (string): The cursor to start from.
    • limit (number): Max number of users to return.
    • orderBy (string): Field to sort by ("signedUpAt").
    • desc (boolean): Sort descending.
    • query (string): Free-text search.

Returns

ServerUser[]

Example 

const users = await stackServerApp.useUsers({ limit: 20 });

stackServerApp.createUser([options])

Creates a new user from the server.

Parameters

  • options (object):
    • primaryEmail (string)
    • primaryEmailVerified (boolean)
    • primaryEmailAuthEnabled (boolean)
    • password (string)
    • otpAuthEnabled (boolean)
    • displayName (string)

Returns

Promise<ServerUser>

Example 

const user = await stackServerApp.createUser({
  primaryEmail: 'test@example.com',
  primaryEmailAuthEnabled: true,
  password: 'password123',
});

stackServerApp.getTeam(id)

Gets a team by its ID.

Parameters

  • id (string): The team ID.

Returns

Promise<ServerTeam | null>

Example 

const team = await stackServerApp.getTeam('team_id');

stackServerApp.useTeam(id)

Functionally equivalent to getTeam(id), but as a React hook.

Parameters

  • id (string): The team ID.

Returns

ServerTeam

Example 

const team = stackServerApp.useTeam('team_id');

stackServerApp.listTeams()

Lists all teams on the current project.

Returns

Promise<ServerTeam[]>

Example 

const teams = await stackServerApp.listTeams();

stackServerApp.useTeams()

Functionally equivalent to listTeams(), but as a React hook.

Returns

ServerTeam[]

Example 

const teams = stackServerApp.useTeams();

stackServerApp.createTeam([options])

Creates a team.

Parameters

  • options (object):
    • displayName (string): The display name for the team.
    • profileImageUrl (string | null): The URL of the team's profile image, or null to remove.

Returns

Promise<ServerTeam>

Example 

const team = await stackServerApp.createTeam({
  displayName: 'New Team',
  profileImageUrl: 'https://example.com/profile.jpg',
});