User
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Change the stack role of a user | No | Use the updateUsersRoles method of a stack |
| Update another user's account | No | update always changes the signed-in account |
Class-Level Properties
| Property | Type | Access | Default | Description |
|---|---|---|---|---|
| uid | string | Read | From the response | UID of the user. |
| string | Read and write | From the response | Email address of the account. | |
| authtoken | string | Read | From the response | Authtoken of the session, when the response holds one. |
| organizations | Organization[] | Read | From the response | Organizations 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 Name | Returns | Description |
|---|---|---|
| update | The updated user. | Saves the properties of this object. |
| delete | The API response with a notice. | Deletes the signed-in account. |
| requestPassword | The API response with a notice. | Emails a temporary password. |
| resetPassword | The API response with a notice. | Sets a new password with a reset token. |
| getTasks | The 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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Filter for the tasks, as a JSON object. |
| params.sort | string | JSON text naming the sort field and order. |
| params.limit | number | Maximum number of tasks to return. |
| params.skip | number | Number of tasks to skip. |
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.
| Name | Type | Description |
|---|---|---|
| credentials (required) | PasswordReset | Reset token and new password. |
| credentials.resetPasswordToken (required) | string | Token from the reset password email. |
| credentials.password (required) | string | New password. |
| credentials.passwordConfirm (required) | string | New password again, to confirm it. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
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)
}