User

View as Markdown

User

A User holds the details of a Contentstack account, such as its UID, email and name. Use this class to

  • update the details of the signed-in account
  • request a temporary password, or reset the password with a token from email
  • list the workflow tasks assigned to you
  • delete the signed-in account

The login method returns a User in the user key of its response. The getUser method resolves to one.

Instance State

  • The methods exist only on a User built from data that contains an authtoken, such as response.user from login. If you call one on another User, it throws TypeError, because the method is undefined.
  • getUser returns a User with the methods when the Get user response contains an authtoken. Check typeof user.update === 'function' before you call one.
  • The User objects that the users method of a stack returns never contain an authtoken, so they have no methods. They describe the collaborators of the stack.
  • update resolves to a new User that has the methods only when the response contains an authtoken.

Class-Level Notes

Authentication.

  • Every request uses the authtoken of the client that created the object, not the authtoken property of the object. Keep the client signed in while you use the object.

Rate limiting and retry.

  • This SDK retries a request that receives 429 automatically, with configurable delay and attempt limits.

Additional Resource For more information on the retry settings and their defaults, refer to the Contentstack documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Change the stack role of a userNoUse the updateUsersRoles method of a stack
Update another user's accountNoupdate always changes the signed-in account

Class-Level Properties

PropertyTypeAccessDefaultDescription
uidstringReadFrom the responseUID of the user.
emailstringRead and writeFrom the responseEmail address of the account.
authtokenstringReadFrom the responseAuthtoken of the session, when the response holds one.
organizationsOrganization[]ReadFrom the responseOrganizations of the user, as Organization objects.
  • Every other key of the user object in the response, such as first_name, last_name and company, is also a property. Set one and call update to save it.
  • The SDK turns organizations into Organization objects only on a User that has the methods.

Method Index

Manage the signed-in account. Available on a User that has an authtoken.

Method NameReturnsDescription
updateThe updated user.Saves the properties of this object.
deleteThe API response with a notice.Deletes the signed-in account.
requestPasswordThe API response with a notice.Emails a temporary password.
resetPasswordThe API response with a notice.Sets a new password with a reset token.
getTasksThe API response with the tasks assigned to you.Lists your workflow tasks.

Class-Level Snippet

The snippet below signs in, changes the name of the account, and lists the workflow tasks assigned to the user.

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })

  user.first_name = 'Ada'
  user.last_name = 'Lovelace'
  const updated = await user.update()
  console.log(updated.first_name, updated.last_name)

  const tasks = await user.getTasks({ query: { type: 'workflow_stage' }, limit: 10 })
  console.log(tasks.assignments)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

Methods

Each method of the User class has its own section below, with its parameters, validation rules, behavior, and examples.

delete

delete removes the signed-in user account from Contentstack permanently.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Warning A successful delete removes the signed-in account permanently, and you cannot undo it.

Validation

  • There is no client-side validation.
  • delete exists only on a User that holds an authtoken. The User page lists the objects that have it.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one DELETE /v3/user request with every key of param as a query parameter.
  • The request deletes the account of the authtoken that the client sends, whatever account the object describes.
  • Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.

Example

Basic usage: delete the signed-in account

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  const response = await user.delete()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

getTasks

getTasks lists the workflow tasks assigned to you, such as entries waiting in a workflow stage or for publish approval. The following table lists its parameters.

NameTypeDescription
paramsobject

Query parameters for the request.

Default: undefined (sends no query parameters)
params.queryobject

Filter for the tasks, as a JSON object.

Default: API default
params.sortstring

JSON text naming the sort field and order.

Default: API default
params.limitnumber

Maximum number of tasks to return.

Default: API default
params.skipnumber

Number of tasks to skip.

Default: API default

Returns: Promise<Response>. The API response with the tasks assigned to you.

Validation

  • There is no client-side validation.
  • getTasks exists only on a User that holds an authtoken. The User page lists the objects that have it.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one Get all Tasks request, GET /v3/user/assignments, with every key of params as a query parameter.
  • The SDK sends query as URL-encoded JSON. It sends any other object value in bracket form, such as sort[assigned_at]=desc, so pass sort as JSON text with JSON.stringify.
  • The Get all Tasks reference lists query as a required parameter and the stack api_key header as required. getTasks sends no api_key header. To send one, create the client with headers: { api_key: '<API_KEY>' }.
  • getTasks sends one request and returns one page of tasks. Use limit and skip to read the next page.
  • Resolves to the response body. assignments holds the tasks.

Example

Basic usage: list the tasks of your workflow stages

import contentstack from '@contentstack/management'

const client = contentstack.client({ headers: { api_key: '<API_KEY>' } })

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  const response = await user.getTasks({ query: { type: 'workflow_stage' } })
  console.log(response.assignments)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: pending publish approvals, newest first, second page

import contentstack from '@contentstack/management'

const client = contentstack.client({ headers: { api_key: '<API_KEY>' } })

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  const response = await user.getTasks({
    query: { 'job.publishing_rule.status': 0 },
    sort: JSON.stringify({ assigned_at: 'desc' }),
    limit: 10,
    skip: 10
  })
  console.log(response.assignments.length)
} catch (error) {
  console.error(error.errorMessage)
}

requestPassword

requestPassword asks Contentstack to email a temporary password and a reset password token to the email address of this user.

This method takes no parameters.

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation. requestPassword sends the email property of the object, even when it is empty or missing.
  • requestPassword exists only on a User that holds an authtoken. The User page lists the objects that have it.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one Request for a password request, POST /v3/user/forgot_password, with the body { user: { email } }.
  • The API emails a temporary password that signs you in, and a reset password token. Pass the token to resetPassword to set a new password.
  • Resolves to the response body, which carries notice.

Example

Basic usage: request a temporary password

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  const response = await user.requestPassword()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

resetPassword

resetPassword sets a new password for the account with the reset password token from the Contentstack email. The following table lists its parameters.

NameTypeDescription
credentials (required)PasswordReset

Reset token and new password.

Default: Not applicable
credentials.resetPasswordToken (required)string

Token from the reset password email.

Default: Not applicable
credentials.password (required)string

New password.

Default: Not applicable
credentials.passwordConfirm (required)string

New password again, to confirm it.

Default: Not applicable

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation of the token or the passwords. The API rejects a wrong token or passwords that do not match.
  • Throws TypeError if you call resetPassword without an object, because the method reads the three keys from its argument.
  • resetPassword exists only on a User that holds an authtoken. The User page lists the objects that have it.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one Reset password request, POST /v3/user/reset_password, with the body { user: { reset_password_token, password, password_confirmation } }. The SDK renames the three keys to the API names.
  • Get the token from the email that requestPassword triggers.
  • Resolves to the response body, which carries notice.

Example

Basic usage: set a new password with a reset token

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  const response = await user.resetPassword({
    resetPasswordToken: '<RESET_PASSWORD_TOKEN>',
    password: '<PASSWORD>',
    passwordConfirm: '<PASSWORD>'
  })
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

update

update saves the properties of this User object to the signed-in account, such as a new first name or company.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<User>. The updated user.

Validation

  • There is no client-side validation. update sends the properties of the object as they are.
  • update exists only on a User that holds an authtoken. The User page lists the objects that have it.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one Update user request, PUT /v3/user, with every key of param as a query parameter.
  • The body is { user: { ... } } with every property of the object except uid, created_at, created_by, updated_at, updated_by and deleted_at. It includes email, authtoken and organizations. Set the properties you want to change on the object before you call update.
  • The API updates only the details in the body and keeps the rest of the account unchanged.
  • Resolves to a new User that the SDK builds from the user key of the response. The notice of the response is not a property of it. The new object has the methods only when the response user holds an authtoken, so keep the original object for further calls.

Example

Basic usage: change the name and company of the account

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  user.first_name = 'Ada'
  user.last_name = 'Lovelace'
  user.company = 'Docs Test Inc'

  const updated = await user.update()
  console.log(updated.first_name, updated.last_name, updated.company)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

Pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client()

try {
  const { user } = await client.login({ email: '<EMAIL>', password: '<PASSWORD>' })
  user.mobile_number = '5550100'
  const updated = await user.update({ include_orgs: true })
  console.log(updated.mobile_number)
} catch (error) {
  console.error(error.errorMessage)
}