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.

On this page:

CurrentUser

You can call useUser() or stackServerApp.getUser() to get the CurrentUser object.

Table of Contents

1type CurrentUser = {
2  id: string; //$stack-link-to:#currentuserid
3  displayName: string | null; //$stack-link-to:#currentuserdisplayname
4  primaryEmail: string | null; //$stack-link-to:#currentuserprimaryemail
5  primaryEmailVerified: boolean; //$stack-link-to:#currentuserprimaryemailverified
6  profileImageUrl: string | null; //$stack-link-to:#currentuserprofileimageurl
7  signedUpAt: Date; //$stack-link-to:#currentusersignedupat
8  hasPassword: boolean; //$stack-link-to:#currentuserhaspassword
9  clientMetadata: Json; //$stack-link-to:#currentuserclientmetadata
10  clientReadOnlyMetadata: Json; //$stack-link-to:#currentuserclientreadonlymetadata
11  selectedTeam: Team | null; //$stack-link-to:#currentuserselectedteam
12
13  update(data): Promise<void>; //$stack-link-to:#currentuserupdatedata
14  updatePassword(data): Promise<void>; //$stack-link-to:#currentuserupdatepassworddata
15  getAuthHeaders(): Promise<Record<string, string>>; //$stack-link-to:#currentusergetauthheaders
16  getAuthJson(): Promise<{ accessToken: string | null }>; //$stack-link-to:#currentusergetauthjson
17  signOut(): Promise<void>; //$stack-link-to:#currentusersignout
18  delete(): Promise<void>; //$stack-link-to:#currentuserdelete
19
20  getTeam(id): Promise<Team | null>; //$stack-link-to:#currentusergetteamid
21   ⤷ useTeam(id): Team | null; //$stack-link-to:#currentuseruseteamid
22  listTeams(): Promise<Team[]>; //$stack-link-to:#currentuserlistteams
23   ⤷ useTeams(): Team[]; //$stack-link-to:#currentuseruseteams
24  setSelectedTeam(team): Promise<void>; //$stack-link-to:#currentusersetselectedteamteam
25  createTeam(data): Promise<Team>; //$stack-link-to:#currentusercreateteamdata
26  leaveTeam(team): Promise<void>; //$stack-link-to:#currentuserleaveteamteam
27  getTeamProfile(team): Promise<EditableTeamMemberProfile>; //$stack-link-to:#currentusergetteamprofileteam
28   ⤷ useTeamProfile(team): EditableTeamMemberProfile; //$stack-link-to:#currentuseruseteamprofileteam
29
30  hasPermission(scope, permissionId): Promise<boolean>; //$stack-link-to:#currentuserhaspermissionscope-permissionid
31  getPermission(scope, permissionId[, options]): Promise<TeamPermission | null>; //$stack-link-to:#currentusergetpermissionscope-permissionid-options
32   ⤷ usePermission(scope, permissionId[, options]): TeamPermission | null; //$stack-link-to:#currentuserusepermissionscope-permissionid-options
33  listPermissions(scope[, options]): Promise<TeamPermission[]>; //$stack-link-to:#currentuserlistpermissionsscope-options
34   ⤷ usePermissions(scope[, options]): TeamPermission[]; //$stack-link-to:#currentuserusepermissionsscope-options
35
36  listContactChannels(): Promise<ContactChannel[]>; //$stack-link-to:#currentuserlistcontactchannels
37   ⤷ useContactChannels(): ContactChannel[]; //$stack-link-to:#currentuserusecontactchannels
38};

currentUser.id

The user ID as a string. This is the unique identifier of the user.

Type Definition

1declare const id: string;

currentUser.displayName

The display name of the user as a string or null if not set. The user can modify this value.

Type Definition

1declare const displayName: string | null;

currentUser.primaryEmail

The primary email of the user as a string or null. Note that this is not necessarily unique.

Type Definition

1declare const primaryEmail: string | null;

currentUser.primaryEmailVerified

A boolean indicating whether the primary email of the user is verified.

Type Definition

1declare const primaryEmailVerified: boolean;

currentUser.profileImageUrl

The profile image URL of the user as a string or null if no profile image is set.

Type Definition

1declare const profileImageUrl: string | null;

currentUser.signedUpAt

The date and time when the user signed up, as a Date.

Type Definition

1declare const signedUpAt: Date;

currentUser.hasPassword

A boolean indicating whether the user has a password set.

Type Definition

1declare const hasPassword: boolean;

currentUser.clientMetadata

The client metadata of the user as an object. This metadata is visible on the client side but should not contain sensitive or server-only information.

Type Definition

1declare const clientMetadata: Json;

currentUser.clientReadOnlyMetadata

Read-only metadata visible on the client side. This metadata can only be modified on the server side.

Type Definition

1declare const clientReadOnlyMetadata: Json;

currentUser.selectedTeam

The currently selected team for the user, if applicable, as a Team object or null if no team is selected.

Type Definition

1declare const selectedTeam: Team | null;

currentUser.update(data)

Updates the user information.

Parameters

data
objectRequired

The fields to update.

Returns

Promise<void>

Signature

1declare function update(data: {
2  displayName?: string;
3  clientMetadata?: Json;
4  selectedTeamId?: string | null;
5  profileImageUrl?: string | null;
6}): Promise<void>;

Examples

1await user.update({
2  displayName: "New Display Name",
3  clientMetadata: {
4    address: "123 Main St",
5  },
6});

currentUser.getTeam(id)

Gets the team with the specified ID.

Parameters

id
stringRequired

The ID of the team to get.

Returns

Promise<Team | null>: The team object, or null if the team is not found or the user is not a member of the team.

Signature

1declare function getTeam(id: string): Promise<Team | null>;

Examples

1const team = await user.getTeam("teamId");

currentUser.useTeam(id)

Gets the team with the given ID. This is the same as getTeam but is used as a React hook.

Parameters

id
stringRequired

The ID of the team to get.

Returns

Team | null: The team object, or null if the team is not found or the user is not a member of the team.

Signature

1declare function useTeam(id: string): Team | null;

Examples

1const team = user.useTeam("teamId");

currentUser.listTeams()

Lists all the teams the user is a member of.

Parameters

None.

Returns

Promise<Team[]>: The list of teams.

Signature

1declare function listTeams(): Promise<Team[]>;

Examples

1const teams = await user.listTeams();

currentUser.useTeams()

Lists all the teams the user is a member of. This is the same as listTeams but is used as a React hook.

Parameters

None.

Returns

Team[]: The list of teams.

Signature

1declare function useTeams(): Team[];

Examples

1const teams = user.useTeams();

currentUser.setSelectedTeam(team)

Sets the currently selected team for the user.

Parameters

team
Team | nullRequired

The team to set as selected, or null to clear selection.

Returns

Promise<void>

Signature

1declare function setSelectedTeam(team: Team | null): Promise<void>;

Examples

1const team = await user.getTeam("team_id_123");
2await user.setSelectedTeam(team);

currentUser.createTeam(data)

Creates a new team for the user. The user will be added to the team and given creator permissions.

Note: If client-side team creation is disabled in the Stack dashboard, this will throw an error.

Parameters

data
objectRequired

The data for creating the team.

Returns

Promise<Team>: The created team.

Signature

1declare function createTeam(data: {
2  displayName: string;
3  profileImageUrl?: string | null;
4}): Promise<Team>;

Examples

1const team = await user.createTeam({
2  displayName: "New Team",
3  profileImageUrl: "https://example.com/profile.jpg",
4});

currentUser.leaveTeam(team)

Allows the user to leave a team. If the user is not a member of the team, this will throw an error.

Parameters

team
TeamRequired

The team to leave.

Returns

Promise<void>

Signature

1declare function leaveTeam(team: Team): Promise<void>;

Examples

1await user.leaveTeam(team);

currentUser.getTeamProfile(team)

Retrieves the user’s profile within a specific team.

Parameters

team
TeamRequired

The team to retrieve the profile for.

Returns

Promise<EditableTeamMemberProfile>: The user’s editable profile for the specified team.

Signature

1declare function getTeamProfile(team: Team): Promise<EditableTeamMemberProfile>;

Examples

1const profile = await user.getTeamProfile(team);

currentUser.useTeamProfile(team)

Retrieves the user’s profile within a specific team. This is the same as getTeamProfile but is used as a React hook.

Parameters

team
TeamRequired

The team to retrieve the profile for.

Returns

EditableTeamMemberProfile: The user’s editable profile for the specified team.

Signature

1declare function useTeamProfile(team: Team): EditableTeamMemberProfile;

Examples

1const profile = user.useTeamProfile(team);

currentUser.hasPermission(scope, permissionId)

Checks if the user has a specific permission for a team.

Parameters

scope
TeamRequired

The team to check the permission for.

permissionId
stringRequired

The ID of the permission to check.

Returns

Promise<boolean>: Whether the user has the specified permission.

Signature

1declare function hasPermission(scope: Team, permissionId: string): Promise<boolean>;

Examples

1const hasPermission = await user.hasPermission(team, "permissionId");

currentUser.getPermission(scope, permissionId, options?)

Retrieves a specific permission for a user within a team.

Parameters

scope
TeamRequired

The team to retrieve the permission for.

permissionId
stringRequired

The ID of the permission to retrieve.

options
object

An object containing multiple properties.

Returns

Promise<TeamPermission | null>: The permission object, or null if not found.

Signature

1declare function getPermission(scope: Team, permissionId: string, options?: { recursive?: boolean }): Promise<TeamPermission | null>;

Examples

1const permission = await user.getPermission(team, "read_secret_info");

currentUser.usePermission(scope, permissionId, options?)

Retrieves a specific permission for a user within a team, used as a React hook.

Parameters

scope
TeamRequired

The team to retrieve the permission for.

permissionId
stringRequired

The ID of the permission to retrieve.

options
object

An object containing multiple properties.

Returns

TeamPermission | null: The permission object, or null if not found.

Signature

1declare function usePermission(scope: Team, permissionId: string, options?: { recursive?: boolean }): TeamPermission | null;

Examples

1const permission = user.usePermission(team, "read_secret_info");

currentUser.listPermissions(scope[, options])

Lists all permissions the user has for a specified team.

Parameters

scope
TeamRequired

The team to list permissions for.

options
object

An object containing multiple properties.

Returns

Promise<TeamPermission[]>: An array of permissions.

Signature

1declare function listPermissions(scope: Team, options?: { recursive?: boolean }): Promise<TeamPermission[]>;

Examples

1const permissions = await user.listPermissions(team);

currentUser.usePermissions(scope, options?)

Lists all permissions the user has for a specified team, used as a React hook.

Parameters

scope
TeamRequired

The team to retrieve permissions for.

options
object

An object containing multiple properties.

Returns

TeamPermission[]: An array of permissions.

Signature

1declare function usePermissions(scope: Team, options?: { recursive?: boolean }): TeamPermission[];

Examples

1const permissions = user.usePermissions(team);

currentUser.listContactChannels()

Lists all the contact channels of the user.

Parameters

No parameters.

Returns

Promise<ContactChannel[]>: An array of contact channels.

Signature

1declare function listContactChannels(): Promise<ContactChannel[]>;

Examples

1const contactChannels = await user.listContactChannels();

currentUser.useContactChannels()

Lists all the contact channels of the user, used as a React hook.

Parameters

No parameters.

Returns

ContactChannel[]: An array of contact channels.

Signature

1declare function useContactChannels(): ContactChannel[];

Examples

1const contactChannels = user.useContactChannels();

currentUser.updatePassword(data)

Updates the user’s password.

Parameters

data
objectRequired

The fields required for updating the password.

Returns

Promise<void>

Signature

1declare function updatePassword(data: {
2  oldPassword: string;
3  newPassword: string;
4}): Promise<void>;

Examples

1const result = await user.updatePassword({
2  oldPassword: "currentPassword",
3  newPassword: "newPassword",
4});
5if (result.status === "error") {
6  console.error("Error updating password", result.error);
7} else {
8  console.log("Password updated");
9}

currentUser.getAuthHeaders()

Returns headers for sending authenticated HTTP requests to external servers. Most commonly used in cross-origin requests. Similar to getAuthJson, but specifically for HTTP requests.

If you are using tokenStore: "cookie", you don’t need this for same-origin requests. However, most browsers now disable third-party cookies by default, so we must pass authentication tokens by header instead if the client and server are on different hostnames.

This function returns a header object that can be used with fetch or other HTTP request libraries to send authenticated requests.

On the server, you can then pass in the Request object to the tokenStore option of your Stack app. Please note that CORS does not allow most headers by default, so you must include x-stack-auth in the Access-Control-Allow-Headers header of the CORS preflight response.

Parameters

No parameters.

Returns

Promise<Record<string, string>>: An object containing the authentication headers.

Signature

1declare function getAuthHeaders(): Promise<Record<string, string>>;

Examples

1// client
2const res = await fetch("https://api.example.com", {
3  headers: {
4    ...await stackApp.getAuthHeaders()
5    // you can also add your own headers here
6  },
7});
8
9// server
10function handleRequest(req: Request) {
11  const user = await stackServerApp.getUser({ tokenStore: req });
12  return new Response("Welcome, " + user.displayName);
13}

currentUser.getAuthJson()

Creates a JSON-serializable object containing the information to authenticate a user on an external server.

While getAuthHeaders is the recommended way to send authentication tokens over HTTP, your app may use a different protocol, for example WebSockets or gRPC. This function returns a token object that can be JSON-serialized and sent to the server in any way you like.

On the server, you can pass in this token object into the tokenStore option to fetch user details.

Parameters

No parameters.

Returns

Promise<{ accessToken: string | null }>: An object containing the access token.

Signature

1declare function getAuthJson(): Promise<{ accessToken: string | null }>;

Examples

1// client
2const res = await rpcCall(rpcEndpoint, {
3  data: {
4    auth: await stackApp.getAuthJson(),
5  },
6});
7
8// server
9function handleRequest(data) {
10  const user = await stackServerApp.getUser({ tokenStore: data.auth });
11  return new Response("Welcome, " + user.displayName);
12}

currentUser.signOut()

Signs out the user and clears the session.

Parameters

No parameters.

Returns

Promise<void>

Signature

1declare function signOut(): Promise<void>;

Examples

1await user.signOut();

currentUser.delete()

Deletes the user. This action is irreversible and can only be used if client-side user deletion is enabled in the Stack dashboard.

Parameters

No parameters.

Returns

Promise<void>

Signature

1declare function delete(): Promise<void>;

Examples

1await user.delete();

ServerUser

The ServerUser object contains most CurrentUser properties and methods with the exception of those that require an active session (getAuthJson and signOut). It also contains some additional functions that require server-level permissions.

Table of Contents

1type ServerUser = 
2  // Inherits most functionality from CurrentUser
3  & Omit<CurrentUser, "getAuthJson" | "signOut">  //$stack-link-to:#currentuser
4  & {
5    lastActiveAt: Date; //$stack-link-to:#serveruserlastactiveat
6    serverMetadata: Json; //$stack-link-to:#serveruserservermetadata
7
8    update(data): Promise<void>; //$stack-link-to:#serveruserupdatedata
9
10    listContactChannels(): Promise<ContactChannel[]>; //$stack-link-to:#serveruserlistcontactchannels
11     ⤷ useContactChannels(): ContactChannel[]; //$stack-link-to:#serveruserusecontactchannels
12
13    grantPermission(scope, permissionId): Promise<void>; //$stack-link-to:#serverusergrantpermissionscope-permissionid
14    revokePermission(scope, permissionId): Promise<void>; //$stack-link-to:#serveruserrevokepermissionscope-permissionid
15  };

serverUser.lastActiveAt

The last active date and time of the user as a Date.

Type Definition

1declare const lastActiveAt: Date;

serverUser.serverMetadata

The server metadata of the user, accessible only on the server side.

Type Definition

1declare const serverMetadata: Json;

serverUser.update(data)

Updates the user’s information on the server side. This is similar to the CurrentUser.update() method but includes additional capabilities, such as updating server metadata or setting a new password directly.

Parameters

data
objectRequired

The fields to update.

Returns

Promise<void>

Signature

1declare function update(data: {
2  displayName?: string;
3  profileImageUrl?: string | null;
4  primaryEmail?: string,
5  primaryEmailVerified?: boolean,
6  primaryEmailAuthEnabled?: boolean,
7  password?: string;
8  selectedTeamId?: string | null;
9  clientMetadata?: Json;
10  clientReadOnlyMetadata?: Json;
11  serverMetadata?: Json;
12}): Promise<void>;

Examples

1await serverUser.update({
2  displayName: "Updated Display Name",
3  password: "newSecurePassword",
4  serverMetadata: {
5    internalNote: "Confidential information",
6  },
7});

serverUser.listContactChannels()

Lists all the contact channels of the user on the server side. This is similar to CurrentUser.listContactChannels() but returns a list of ServerContactChannel objects, which may include additional server-only details.

Parameters

No parameters.

Returns

Promise<ServerContactChannel[]>: An array of server-specific contact channels.

Signature

1declare function listContactChannels(): Promise<ServerContactChannel[]>;

Examples

1const contactChannels = await serverUser.listContactChannels();

serverUser.useContactChannels()

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 of useUser).
  • Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg. CurrentUser instead of CurrentServerUser).
  • 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 listContactChannels(), but as a React hook.

serverUser.grantPermission(scope, permissionId)

Grants a specific permission to the user for a given team.

Parameters

scope
TeamRequired

The team to grant the permission for.

permissionId
stringRequired

The ID of the permission to grant.

Returns

Promise<void>

Signature

1declare function grantPermission(scope: Team, permissionId: string): Promise<void>;

Examples

1await serverUser.grantPermission(team, "read_secret_info");

serverUser.revokePermission(scope, permissionId)

Revokes a specific permission from the user for a given team.

Parameters

scope
TeamRequired

The team to revoke the permission from.

permissionId
stringRequired

The ID of the permission to revoke.

Returns

Promise<void>

Signature

1declare function revokePermission(scope: Team, permissionId: string): Promise<void>;

Examples

1await serverUser.revokePermission(team, "read_secret_info");

CurrentServerUser

The CurrentServerUser object combines all the properties and methods of both CurrentUser and ServerUser. You can obtain a CurrentServerUser by calling stackServerApp.getUser() on the server side.

Table of Contents

1type CurrentServerUser =
2  // Inherits all functionality from CurrentUser
3  & CurrentUser  //$stack-link-to:#currentuser
4  // Inherits all functionality from ServerUser
5  & ServerUser;  //$stack-link-to:#serveruser