User
This is a detailed reference for the User
object. If you’re looking for a more high-level overview, please refer to our guide on users here.
Different types of User
objects
There are a few types of user objects in Stack Auth:
-
CurrentUser
- Represents the authenticated user on the client side
- Has an active session (typically stored in browser cookies)
- Used in client-side code
- Obtained by calling
useUser()
in a Client Component
-
ServerUser
- Represents a user on the server side without an active session
- extends most of the attributes and methods of
CurrentUser
- Has additional capabilities like being able to update emails or passwords without confirmation
- Lacks session-dependent functions like
signOut()
- Obtained by calling
stackServerApp.getUser('user_id_123')
orstackServerApp.listUsers()
on the server side
-
CurrentServerUser
- Combines attributes and methods of both
ServerUser
andCurrentUser
- Obtained by calling
stackServerApp.getUser()
on the server side
- Combines attributes and methods of both
These user types provide flexible and secure user management across both client and server environments, each serving a specific purpose in different application contexts.
CurrentUser
You can call useUser()
or stackServerApp.getUser()
to get the CurrentUser
object.
Properties
The user ID. This is the unique identifier of the user.
The display name of the user. Can be changed by the user.
The primary email of the user. Note: this is not unique.
Whether the primary email is verified.
The profile image URL of the user.
The Date when the user signed up.
Whether the user has a password set.
The JSON metadata that is visible on the client side. Note that this should not contain information that should be kept private on the server side or information that should not be modified by the client.
Metadata that can be read on the client side but can only be modified on the server side.
The currently selected team for the user, if applicable.
update()
Update the user information.
Parameters:
The new display name for the user.
Custom metadata visible to the client.
The ID of the team to set as selected, or null to clear selection.
The URL of the user’s new profile image (base64 image allowed, crop and compress before passing it in), or null to remove.
Returns:
Promise<void>
Example:
getTeam()
Get the team with the given ID.
Parameters:
The ID of the team to get.
Returns:
Promise<Team | null>
: The team object, or null if the team is not found (either because it doesn’t exist or because the user is not a member of the team).
Example:
useTeam()
Get the team with the given ID.
This is the same as getTeam
but it is a React hook.
Parameters:
The ID of the team to get.
Returns:
Team | null
: The team object, or null if the team is not found (either because it doesn’t exist or because the user is not a member of the team).
Example:
listTeams()
List all the teams the user is a member of.
Parameters:
No parameters.
Returns:
Promise<Team[]>
: The list of teams.
Example:
useTeams()
List all the teams the user is a member of.
This is the same as listTeams
but it is a React hook.
Parameters:
No parameters.
Returns:
Team[]
: The list of teams.
Example:
setSelectedTeam()
Parameters:
The team to set as selected, or null to clear selection.
Returns:
Promise<void>
Set the currently selected team for the user.
Example:
createTeam()
Create a new team for the user. The user will be added to the team and be given the creator permissions.
Note that if client side team creation is disabled in the Stack dashboard, this will throw an error.
Parameters:
The display name for the team.
The URL of the team’s profile image (base64 image allowed, crop and compress before passing it in), or null to remove.
Returns:
Promise<Team>
: The created team.
Example:
leaveTeam()
Leave a team.
Note that if the user is not a member of the team, this will throw an error.
Parameters:
The team to leave.
Returns:
Promise<void>
Example:
getTeamProfile()
Get the user’s profile for a team.
Parameters:
The team to get the profile for.
Returns:
Promise<EditableTeamMemberProfile>
: The editable team member profile
Example:
useTeamProfile()
Get the user’s profile for a team.
This is the same as getTeamProfile
but it is a React hook.
Parameters:
The team to get the profile for.
Returns:
EditableTeamMemberProfile
: The editable team member profile
Example:
hasPermission()
Parameters:
The team to check the permission for.
The ID of the permission to check.
Returns:
Promise<boolean>
: Whether the user has the permission.
This will check if the user has a permission for a team. Note that if the permission is not defined in the Stack dashboard, it will still return false.
Example:
getPermission()
Parameters:
The team to get the permission for.
The ID of the permission to get.
Whether to get the permission recursively. default true
.
Returns:
Promise<TeamPermission | null>
: The permission object, or null if the permission is not found.
This will get the permission of a user for a team. Note that if the permission is not defined in the Stack dashboard, it will still return null.
Example:
usePermission()
TeamPermission | null
: The permission object, or null if the permission is not found.
This will get the permission of a user for a team. Note that if the permission is not defined in the Stack dashboard, it will still return null.
This is the same as getPermission
but it is a React hook.
Parameters:
The team to get the permission for.
The ID of the permission to get.
Whether to get the permission recursively. default true
.
Returns:
TeamPermission | null
: The permission object, or null if the permission is not found.
Example:
listPermissions()
List all the permissions a user has for a team.
Parameters:
The team to list the permissions for.
Whether to list the permissions recursively. default true
.
Returns:
Promise<TeamPermission[]>
: The list of permissions.
Example:
usePermissions()
List all the permissions a user has for a team.
This is the same as listPermissions
but it is a React hook.
Parameters:
The team to use the permissions for.
Whether to use the permissions recursively. default true
.
Returns:
TeamPermission[]
: The list of permissions.
Example:
updatePassword()
This will update the user’s password. It will return an error object (not throw an error) if the passwords mismatch or if the new password does not meet the requirements. If successful, it will return undefined.
Parameters:
The old password.
The new password.
Returns:
Promise<void>
Example:
getAuthJson()
This will return the authentication tokens of the user. This is normally then used for authentication to an external server. See more details here.
Parameters:
No parameters.
Returns:
Promise<{ accessToken: string | null }>
Example:
signOut()
This will sign out the user and clear the session.
Parameters:
No parameters.
Returns:
Promise<void>
Example:
delete()
Delete the user. Use it with caution as it is irreversible. Note that this only works if the “allow client side user deletion” option is enabled in the Stack dashboard.
Parameters:
No parameters.
Returns:
Promise<void>
Example:
ServerUser
ServerUser
is only available on the server side. Some of the methods on the StackServerApp
return ServerUser
objects, for example stackServerApp.listUsers()
or stackServerApp.getUser('user_id_123')
.
The ServerUser
object contains everything in the CurrentUser
object, except for the following methods:
signOut()
getAuthJson()
It also has some additional properties and methods (some of the methods have the same name but more capabilities):
Properties
The last active at date of the user.
The server metadata of the user. Only readable and writable on the server side.
update()
Update the user information.
This is similar to the CurrentUser.update()
method, but is strictly more powerful (like update password, update server metadata, etc.)
Parameters:
The new display name for the user.
Custom metadata visible to the client.
The ID of the team to set as selected, or null to clear selection.
The URL of the user’s new profile image (base64 image allowed, crop and compress before passing it in), or null to remove.
Metadata that can be read on the client side but can only be modified on the server side.
Metadata that can be read and modified on the server side.
The new password for the user.
Returns:
Promise<void>
Example:
grantPermission()
Grant a permission to a user for a team.
This action will still succeed if the permission is already granted. It will throw an error if the permission is not defined in the Stack dashboard.
Parameters:
The team to grant the permission to.
The ID of the permission to grant.
Returns:
Promise<void>
Example:
revokePermission()
Revoke a permission from a user for a team.
This action will still succeed if the permission is not granted in the first place. It will throw an error if the permission is not defined in the Stack dashboard.
Parameters:
The team to revoke the permission from.
The ID of the permission to revoke.
Returns:
Promise<void>
Example:
CurrentServerUser
The CurrentServerUser
has the same properties and methods from ServerUser
and CurrentUser
combined (for the overloaded methods like update
, the ServerUser
methods take precedence).
To get a CurrentServerUser
object, you can use the stackServerApp.getUser()
method. Note that this can only be used on the server side.