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.

clearStatus()

clearStatus(): 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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Clears the session user's shared status. Requires the user:write scope.

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; status?: | { activeUntil?: string | null; effects?: { pauseActivity?: { scope?: { mode?: ... | ...; }; }; pauseNotifications?: { scope?: { mode?: ... | ...; }; }; }; emoji?: string | null; message: string; } | null; timezone: string; token?: string | null; }>

The updated user object.

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Gets the user associated with the current access token.

Returns

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

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

Returns

The user object with the new token.

Example

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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Logs in an existing user.

Parameters

Parameter	Type	Description
`args`	`LoginArgs`	Login credentials.

Returns

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Registers a new user via the Todoist-ID bridge.

Parameters

Parameter	Type	Description
`args`	`RegisterArgs`	Registration arguments.

Returns

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Removes the user's avatar.

Returns

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>

setStatus()

setStatus(args: SetStatusArgs): 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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  timezone: string;
  token?: string | null;
}>;

Sets the shared status of the session user, replacing any current one. The status belongs to the Todoist account, so it is shared with Todoist. Requires the user:write scope.

Parameters

Parameter	Type	Description
`args`	`SetStatusArgs`	The status to set.

Returns

The updated user object.

Example

await api.users.setStatus({
  message: 'Deep work',
  emoji: '🎯',
  activeUntil: new Date(Date.now() + 2 * 60 * 60 * 1000),
  effects: { pauseNotifications: {} },
})

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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;
  status?:   | {
     activeUntil?: string | null;
     effects?: {
        pauseActivity?: {
           scope?: {
              mode?: ... | ...;
           };
        };
        pauseNotifications?: {
           scope?: {
              mode?: ... | ...;
           };
        };
     };
     emoji?: string | null;
     message: string;
   }
     | null;
  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

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>

Extends​

Constructors​

Constructor​

Parameters​

Returns​

Inherited from​

Properties​

Methods​

checkEmail()​

Parameters​

Returns​

clearStatus()​

Returns​

getBaseUri()​

Returns​

Inherited from​

getLinkBaseUrl()​

Returns​

Inherited from​

getSessionUser()​

Returns​

Example​

getUnsubscribeSettings()​

Returns​

getUser()​

Parameters​

Returns​

getUserByEmail()​

Parameters​

Returns​

heartbeat()​

Parameters​

Returns​

Example​

invalidateToken()​

Returns​

Example​

login()​

Parameters​

Returns​

Example​

loginWithGoogle()​

Parameters​

Returns​

loginWithTodoist()​

Returns​

loginWithToken()​

Returns​

logout()​

Returns​

mfaChallenge()​

Parameters​

Returns​

register()​

Parameters​

Returns​

removeAvatar()​

Returns​

resetPresence()​

Parameters​

Returns​

setStatus()​

Parameters​

Returns​

Example​

update()​

Parameters​

Returns​

Example​

updatePassword()​

Parameters​

Returns​

updateUnsubscribeSettings()​

Parameters​

Returns​

validateToken()​

Parameters​

Returns​

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

Methods

checkEmail()

Parameters

Returns

clearStatus()

Returns

getBaseUri()

Returns

Inherited from

getLinkBaseUrl()

Returns

Inherited from

getSessionUser()

Returns

Example

getUnsubscribeSettings()

Returns

getUser()

Parameters

Returns

getUserByEmail()

Parameters

Returns

heartbeat()

Parameters

Returns

Example

invalidateToken()

Returns

Example

login()

Parameters

Returns

Example

loginWithGoogle()

Parameters

Returns

loginWithTodoist()

Returns

loginWithToken()

Returns

logout()

Returns

mfaChallenge()

Parameters

Returns

register()

Parameters

Returns

removeAvatar()

Returns

resetPresence()

Parameters

Returns

setStatus()

Parameters

Returns

Example

update()

Parameters

Returns

Example

updatePassword()

Parameters

Returns

updateUnsubscribeSettings()

Parameters

Returns

validateToken()

Parameters

Returns