UsersClient

Client for the /api/v1/users/ endpoints. Authentication flows through Todoist-ID; register / login / loginWithGoogle / loginWithToken / loginWithTodoist are the available entry points.

Extends

• BaseClient

Constructors

Constructor

new UsersClient(config: ClientConfig): UsersClient;

Parameters

Parameter	Type
config	ClientConfig

Returns

UsersClient

Inherited from

BaseClient.constructor

Properties

Property	Modifier	Type
apiToken	readonly	string
baseUrl?	readonly	string
customFetch?	readonly	CustomFetch
defaultVersion	readonly	"v1"

Methods

checkEmail()

checkEmail(email: string): Promise<EmailExistsResponse>;

Checks whether an email address is registered (and verified).

Parameters

Parameter	Type	Description
email	string	The email to check.

Returns

Promise<EmailExistsResponse>

Object indicating whether the email exists and is verified.

---

getBaseUri()

protected getBaseUri(): string;

Returns the base URI for an API request, with a guaranteed trailing slash so relative paths resolve cleanly through URL.

Returns

string

Inherited from

BaseClient.getBaseUri

---

getLinkBaseUrl()

protected getLinkBaseUrl(): string | undefined;

Base URL for entity web links, or undefined to use getFullCommsURL's default web app. Trailing-slash normalization happens in getFullCommsURL, so the configured value is returned verbatim.

Returns

string | undefined

Inherited from

BaseClient.getLinkBaseUrl

---

getSessionUser()

getSessionUser(): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Gets the user associated with the current access token.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The authenticated user's information.

Example

const user = await api.users.getSessionUser()
console.log(user.fullName, user.email)

---

getUnsubscribeSettings()

getUnsubscribeSettings(): Promise<Record<string, boolean>>;

Returns the current per-channel mail unsubscribe settings for the caller's primary email.

Returns

Promise<Record<string, boolean>>

Object mapping email-type keys to their opt-out flag.

---

getUser()

getUser(args?: {
  asList?: boolean;
  id?: number;
  workspaceId?: number;
}): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Fetches a single user. Defaults to the session user when no id is passed. Cross-workspace lookups require that the caller and the target share a workspace.

Parameters

Parameter	Type	Description
args?	{ asList?: boolean; id?: number; workspaceId?: number; }	Optional lookup arguments.
args.asList?	boolean	Optional flag controlling list-style response.
args.id?	number	The user ID. Defaults to the session user.
args.workspaceId?	number	Optional workspace ID for cross-workspace lookups.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The user object.

---

getUserByEmail()

getUserByEmail(email: string): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Looks up a user by their email address.

Parameters

Parameter	Type	Description
email	string	The email to look up.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The user object.

---

heartbeat()

heartbeat(args: {
  platform: string;
  workspaceId: number;
}): Promise<void>;

Marks the user as active on a workspace (presence beacon).

Parameters

Parameter	Type	Description
args	{ platform: string; workspaceId: number; }	Heartbeat arguments.
args.platform	string	The platform identifier (e.g., 'mobile', 'desktop', 'api').
args.workspaceId	number	The workspace ID.

Returns

Promise<void>

Example

await api.users.heartbeat({ workspaceId: 123, platform: 'api' })

---

invalidateToken()

invalidateToken(): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Invalidates the current API token and returns the user with a fresh token.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The user object with the new token.

Example

const user = await api.users.invalidateToken()
console.log('New token:', user.token)

---

login()

login(args: LoginArgs): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Logs in an existing user.

Parameters

Parameter	Type	Description
args	LoginArgs	Login credentials.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The authenticated user object.

Example

const user = await api.users.login({
  email: 'user@example.com',
  password: 'secret',
})

---

loginWithGoogle()

loginWithGoogle(args: LoginWithGoogleArgs): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Logs in (and auto-signs-up) via a Google ID token.

Parameters

Parameter	Type	Description
args	LoginWithGoogleArgs	Google login arguments.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The authenticated user object.

---

loginWithTodoist()

loginWithTodoist(): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Exchanges the browser's Todoist web-session cookie for a Comms session. Only useful when running in a browser context on the shared Todoist registrable domain — the cookie is sent automatically by the browser.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The authenticated user object.

---

loginWithToken()

loginWithToken(): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Logs in using a valid token (sent via Authorization header). The SDK client is already configured with the token, so no args are needed.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The authenticated user object.

---

logout()

logout(): Promise<void>;

Logs out the current user and clears the session cookie.

Returns

Promise<void>

---

mfaChallenge()

mfaChallenge(args: MfaChallengeArgs): Promise<MfaChallengeResponse>;

Completes an MFA challenge issued by loginWithGoogle (returns an MFA token to pass back to loginWithGoogle.mfaToken).

Parameters

Parameter	Type	Description
args	MfaChallengeArgs	MFA challenge arguments.

Returns

Promise<MfaChallengeResponse>

The MFA token to forward to loginWithGoogle.

---

register()

register(args: RegisterArgs): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Registers a new user via the Todoist-ID bridge.

Parameters

Parameter	Type	Description
args	RegisterArgs	Registration arguments.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The newly registered user object.

---

removeAvatar()

removeAvatar(): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Removes the user's avatar.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The updated user object.

---

resetPresence()

resetPresence(workspaceId: number): Promise<void>;

Resets the user's presence for a workspace (marks the user as inactive).

Parameters

Parameter	Type	Description
workspaceId	number	The workspace ID.

Returns

Promise<void>

---

update()

update(args: UpdateUserArgs): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Updates the logged-in user's profile. Most fields are proxied to Todoist (full name, password, language, timezone, etc.).

Parameters

Parameter	Type	Description
args	UpdateUserArgs	The user properties to update.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The updated user object.

Example

const user = await api.users.update({
  name: 'John Doe',
  timezone: 'America/New_York',
})

---

updatePassword()

updatePassword(args: {
  currentPassword?: string;
  newPassword: string;
}): Promise<{
  avatarUrls?:   | {
     s195: string;
     s35: string;
     s60: string;
     s640: string;
   }
     | null;
  clientId?: string | null;
  cometChannel?: string | null;
  cometServer?: string | null;
  email: string;
  firstName?: string | null;
  fullName: string;
  id: number;
  imageId?: string | null;
  lang: string;
  removed: boolean;
  restricted?: boolean | null;
  scheduledBanners?: string[] | null;
  setupPending?: boolean | null;
  shortName: string;
  timezone: string;
  token?: string | null;
}>;

Updates the user's password.

Parameters

Parameter	Type	Description
args	{ currentPassword?: string; newPassword: string; }	Password update arguments.
args.currentPassword?	string	The user's existing password. Optional — sent for re-authentication when the account has a password set.
args.newPassword	string	The new password.

Returns

Promise<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; clientId?: string | null; cometChannel?: string | null; cometServer?: string | null; email: string; firstName?: string | null; fullName: string; id: number; imageId?: string | null; lang: string; removed: boolean; restricted?: boolean | null; scheduledBanners?: string[] | null; setupPending?: boolean | null; shortName: string; timezone: string; token?: string | null; }>

The updated user object.

---

updateUnsubscribeSettings()

updateUnsubscribeSettings(settings: Record<string, boolean>): Promise<{
  status: string;
}>;

Toggles per-email-type opt-out settings.

Parameters

Parameter	Type	Description
settings	Record<string, boolean>	Object mapping email-type keys to their opt-out flag.

Returns

Promise<{ status: string; }>

Status object with "ok" status.

---

validateToken()

validateToken(token: string): Promise<void>;

Validates that an arbitrary token is still active. Note this is sent as a GET — the token is read from the query string, not the Authorization header.

Parameters

Parameter	Type	Description
token	string	The token to validate.

Returns

Promise<void>