StackApp
This is a detailed reference for the StackApp
object. If you’re looking for a more high-level overview, please read the respective page in the Concepts section.
On this page:
StackClientApp
A StackApp
with client-level permissions. It contains most of the useful methods and hooks for your client-side code.
Most commonly you get an instance of StackClientApp
by calling useStackApp()
in a Client Component.
Table of Contents
Constructor
Creates a new StackClientApp
instance.
Because each app creates a new connection to Stack Auth’s backend, you should re-use existing instances wherever possible.
This object is not usually constructed directly. More commonly, you would construct a StackServerApp
instead, pass it into a <StackProvider />
, and then use useStackApp()
hook to obtain a StackClientApp
.
The setup wizard does these steps for you, so you don’t need to worry about it unless you are manually setting up Stack Auth.
If you’re building a client-only app and don’t have a SECRET_SERVER_KEY
, you can construct a StackClientApp
directly.
Parameters
An object containing multiple properties.
Signature
Examples
stackClientApp.getUser([options])
Gets the current user.
Parameters
An object containing multiple properties.
Returns
Promise<CurrentUser | null>
: The current user, or null
if not signed in. If or
is "redirect"
or "throw"
, never returns null
.
Signature
Examples
stackClientApp.useUser([options])
Functionally equivalent to getUser()
, but as a React hook.
Equivalent to the useUser()
standalone hook (which is an alias for useStackApp().useUser()
).
Parameters
An object containing multiple properties.
Returns
CurrentUser | null
: The current user, or null
if not signed in. If or
is "redirect"
or "throw"
, never returns null
.
Signature
Examples
stackClientApp.getProject()
Gets the current project.
Parameters
No parameters.
Returns
Promise<Project>
: The current project.
Signature
Examples
stackClientApp.useProject()
Functionally equivalent to getProject()
, but as a React hook.
Parameters
No parameters.
Returns
Project
: The current project.
Signature
Examples
stackClientApp.signInWithOAuth(provider)
Initiates the OAuth sign-in process with the specified provider. This method:
- Redirects the user to the OAuth provider’s sign-in page.
- After successful authentication, redirects the user back to your application.
- The final redirect destination is determined as follows:
- If an
after_auth_return_to
query parameter was provided when calling this function, it uses that URL. - Otherwise, it uses the
afterSignIn
URL configured in the app settings.
- If an
Parameters
The type of the OAuth provider to sign in with.
Returns
Promise<void>
.
Signature
Examples
stackClientApp.signInWithCredential([options])
Sign in using email and password credentials. The behavior is as follows:
-
If sign-in is successful:
- By default, redirects the user to the
afterSignIn
URL. - If
after_auth_return_to
is provided in the query parameters, redirects to that URL instead. - If
noRedirect
is set totrue
, it will not redirect and instead return a successResult
object.
- By default, redirects the user to the
-
If sign-in fails:
- No redirection occurs.
- Returns a
Result
object containing error information.
Parameters
An object containing multiple properties.
Returns
Promise<Result<undefined, KnownErrors["EmailPasswordMismatch"]>>
: A promise that resolves to a Result
object.
Signature
Examples
stackClientApp.signUpWithCredential([options])
Sign up using email and password credentials. The behavior is as follows:
-
If sign-up is successful:
- By default, redirects the user to the
afterSignUp
URL. - If
after_auth_return_to
is provided in the query parameters, redirects to that URL instead. - If
noRedirect
is set totrue
, it will not redirect and instead return a successResult
object.
- By default, redirects the user to the
-
If sign-up fails:
- No redirection occurs.
- Returns a
Result
object containing error information.
Parameters
An object containing multiple properties.
Returns
Promise<Result<undefined, KnownErrors["UserEmailAlreadyExists"] | KnownErrors["PasswordRequirementsNotMet"]>>
: A promise that resolves to a Result
object.
Signature
Examples
stackClientApp.sendForgotPasswordEmail(email)
Send a forgot password email to an email address.
Parameters
The email of the user to send the forgot password email to.
Returns
Promise<Result<undefined, KnownErrors["UserNotFound"]>>
: A promise that resolves to a Result
object.
Signature
Examples
stackClientApp.sendMagicLinkEmail(email)
Send a magic link/OTP sign-in email to an email address.
Parameters
The email of the user to send the magic link email to.
Returns
Promise<Result<{ nonce: string }, KnownErrors["RedirectUrlNotWhitelisted"]>>
: A promise that resolves to a Result
object.
Signature
Examples
StackServerApp
Like StackClientApp
, but with server permissions. Has full read and write access to all users.
Since this functionality should only be available in environments you trust (ie. your own server), it requires a SECRET_SERVER_KEY
. In some cases, you may want to use a StackServerApp
on the client; an example for this is an internal dashboard that only your own employees have access to. We generally recommend against doing this unless you are aware of and protected against the (potentially severe) security implications of exposing SECRET_SERVER_KEY
on the client.
Table of Contents
Constructor
Parameters
An object containing multiple properties.
Signature
Examples
stackServerApp.getUser([id], [options])
Similar to StackClientApp.getUser()
, but:
- Returns a
ServerUser
, which is more powerful - Has an additional overload that takes an
id
parameter instead ofoptions
, returning the user with the given ID instead of the current user.
Parameters
The ID of the user to get.
An object containing multiple properties.
Returns
Promise<ServerUser | null>
: The user, or null if not found. If id
is not provided, returns a CurrentServerUser
.
If id
is not provided and or
is "redirect"
or "throw"
, never returns null
.
Signature
Examples
stackServerApp.useUser([id][, options])
This is the documentation for a React hook on a server type. This is uncommon, because server types are only available with server permissions and React Server Components do not use hooks. Ask yourself if you:
- Want to use this on the server, eg. in a React Server Component? Look for the respective function without the
use
prefix (eg.getUser
instead ofuseUser
). - Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg.
CurrentUser
instead ofCurrentServerUser
). - Are an advanced user, building an internal tool, and confident that you are securing
SECRET_SERVER_KEY
correctly? Then this is for you.
Functionally equivalent to getUser()
, but as a React hook.
stackServerApp.listUsers([options])
Lists all users on the project.
Parameters
An object containing multiple properties.
Returns
Promise<ServerUser[]>
: The list of users. The array has an additional nextCursor
property, which is the cursor to the next page of users if limit
is provided.
Signature
Examples
stackServerApp.useUsers([options])
This is the documentation for a React hook on a server type. This is uncommon, because server types are only available with server permissions and React Server Components do not use hooks. Ask yourself if you:
- Want to use this on the server, eg. in a React Server Component? Look for the respective function without the
use
prefix (eg.getUser
instead ofuseUser
). - Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg.
CurrentUser
instead ofCurrentServerUser
). - Are an advanced user, building an internal tool, and confident that you are securing
SECRET_SERVER_KEY
correctly? Then this is for you.
Functionally equivalent to listUsers()
, but as a React hook.
stackServerApp.createUser([options])
Creates a new user from the server.
Note that this function is meant for server-side code; on the client, use any of the signInWithXyz
or signUpWithXyz
functions instead.
Parameters
An object containing multiple properties.
Returns
Promise<ServerUser>
: The created user.
Signature
Examples
stackServerApp.getTeam(id)
Get a team by its ID.
Parameters
The ID of the team to get.
Returns
Promise<ServerTeam | null>
: The team, or null if not found.
Signature
Examples
stackServerApp.useTeam(id)
This is the documentation for a React hook on a server type. This is uncommon, because server types are only available with server permissions and React Server Components do not use hooks. Ask yourself if you:
- Want to use this on the server, eg. in a React Server Component? Look for the respective function without the
use
prefix (eg.getUser
instead ofuseUser
). - Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg.
CurrentUser
instead ofCurrentServerUser
). - Are an advanced user, building an internal tool, and confident that you are securing
SECRET_SERVER_KEY
correctly? Then this is for you.
Functionally equivalent to getTeam(id)
, but as a React hook.
stackServerApp.listTeams()
Lists all teams on the current project.
Parameters
None.
Returns
Promise<ServerTeam[]>
: All teams on the current project.
Signature
Examples
stackServerApp.useTeams()
This is the documentation for a React hook on a server type. This is uncommon, because server types are only available with server permissions and React Server Components do not use hooks. Ask yourself if you:
- Want to use this on the server, eg. in a React Server Component? Look for the respective function without the
use
prefix (eg.getUser
instead ofuseUser
). - Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg.
CurrentUser
instead ofCurrentServerUser
). - Are an advanced user, building an internal tool, and confident that you are securing
SECRET_SERVER_KEY
correctly? Then this is for you.
Functionally equivalent to listTeams()
, but as a React hook.
stackServerApp.createTeam([options])
Creates a team.
This is different from user.createTeam()
because it does not add a user to the team. The newly created team will not have a creator.
Parameters
Returns
Promise<ServerTeam>
: The created team.