User
User
User represents the Contentstack account that the client uses after login. Every account registered with Contentstack is a user, and a stack can have many users with different roles.
Use this class for the four tasks below:
- read the details of the logged-in account, including the stacks it owns and shares
- update the account profile, such as the name or company
- activate a new account, request a password reset and reset a password
- end the session of the logged-in account
activateAccount
activateAccount activates a new Contentstack account with the token from the activation email, and sets the name and password of the account.
| Name | Type | Description |
|---|---|---|
| activationToken (required) | String | Token from the activation URL in the sign-up email. |
| body (required) | JSONObject | Account details, under a user key. |
| body.user.first_name (required) | String | First name of the account. |
| body.user.last_name (required) | String | Last name of the account. |
| body.user.password (required) | String | Password to set. |
| body.user.password_confirmation (required) | String | Same password again. |
Returns: Call<ResponseBody>. The request for the account activation, sent when you call execute().
Validation
- There is no client-side validation. activateAccount sends the token and body as given.
- A null activationToken makes execute() throw IllegalArgumentException, because Retrofit cannot build the request path without it.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- activateAccount builds a POST /user/activate/{user_activation_token} request and sends nothing until you call execute().
- client.user() needs a logged-in client, so call activateAccount from a client that already holds a session.
Example
Basic usage: activate an account
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ActivateAccount {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
JSONObject fields = new JSONObject();
fields.put("first_name", "Jane");
fields.put("last_name", "Doe");
fields.put("password", "<PASSWORD>");
fields.put("password_confirmation", "<PASSWORD>");
JSONObject body = new JSONObject();
body.put("user", fields);
// The activation token is the last part of the activation URL in the sign-up email
String activationToken = args[0];
Response<ResponseBody> response = client.user().activateAccount(activationToken, body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeader
addHeader stores one request header on the User object. No User request in 1.16.0 sends the stored values.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Header name. |
| value (required) | String | Header value. |
Returns: User. The same user, for chaining.
Validation
- There is no client-side validation.
- addHeader stores a null key or value as is.
Behavior
- Client-side only. addHeader stores the values in a map on the User object and makes no request.
- No User request reads that map, so the values do not reach the API. Every request sends only the headers that the SDK sets, such as the client's authtoken.
- A later value for the same key replaces the earlier one.
Example
Basic usage: store a value on the user object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.user.User;
import java.io.IOException;
public class StoreUserHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
User user = client.user().addHeader("x-request-id", "docs-test-request");
System.out.println("User object: " + user);
}
}addHeaders
addHeaders stores several request headers on the User object. No User request in 1.16.0 sends the stored values.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap | Header names and values. |
Returns: User. The same user, for chaining.
Validation
- There is no client-side validation.
- A null map throws NullPointerException.
Behavior
- Client-side only. addHeaders stores the values in a map on the User object and makes no request.
- No User request reads that map, so the values do not reach the API. Every request sends only the headers that the SDK sets, such as the client's authtoken.
- A later value for the same key replaces the earlier one.
Example
Basic usage: store a value on the user object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.user.User;
import java.io.IOException;
import java.util.HashMap;
public class StoreUserHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
HashMap<String, String> headers = new HashMap<>();
headers.put("x-request-id", "docs-test-request");
User user = client.user().addHeaders(headers);
System.out.println("User object: " + user);
}
}addParam
addParam stores one query parameter on the User object. No User request in 1.16.0 sends the stored values.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Query parameter name. |
| value (required) | Object | Query parameter value. |
Returns: User. The same user, for chaining.
Validation
- There is no client-side validation.
- addParam stores a null key or value as is.
Behavior
- Client-side only. addParam stores the values in a map on the User object and makes no request.
- No User request reads that map, so the values do not reach the API. Every request sends only the headers that the SDK sets, such as the client's authtoken.
- A later value for the same key replaces the earlier one.
Example
Basic usage: store a value on the user object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.user.User;
import java.io.IOException;
public class StoreUserParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
User user = client.user().addParam("include_count", true);
System.out.println("User object: " + user);
}
}addParams
addParams stores several query parameters on the User object. No User request in 1.16.0 sends the stored values.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap | Query parameter names and values. |
Returns: User. The same user, for chaining.
Validation
- There is no client-side validation.
- A null map throws NullPointerException.
Behavior
- Client-side only. addParams stores the values in a map on the User object and makes no request.
- No User request reads that map, so the values do not reach the API. Every request sends only the headers that the SDK sets, such as the client's authtoken.
- A later value for the same key replaces the earlier one.
Example
Basic usage: store a value on the user object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.user.User;
import java.io.IOException;
import java.util.HashMap;
public class StoreUserParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
HashMap<String, Object> params = new HashMap<>();
params.put("include_count", true);
User user = client.user().addParams(params);
System.out.println("User object: " + user);
}
}getUser
getUser retrieves the details of the logged-in account, including the stacks the account owns and the stacks shared with it.
Returns: Call<ResponseBody>. The request for the account details, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- getUser builds a GET /user request and sends nothing until you call execute().
- The request carries the client's authtoken, so the response describes the account that logged in.
- The response body is the raw JSON, with the account under a user key. Read it with response.body().string(), or parse it into a UserDetail. See Response models on the User class page.
Example
Basic usage: read the account details
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class GetAccountDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Response<ResponseBody> response = client.user().getUser().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Parse the account into a UserDetail
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.UserDetail;
import com.google.gson.Gson;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ParseAccountDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Response<ResponseBody> response = client.user().getUser().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
UserDetail detail = new Gson().fromJson(response.body().string(), UserDetail.class);
System.out.println(detail.getUser().getFirstName() + " " + detail.getUser().getLastName());
}
}login
login builds a login request for an email address and password, and returns it as a typed call. It does not store the returned authtoken on the client.
| Name | Type | Description |
|---|---|---|
| email (required) | String | Email address of the Contentstack account. |
| password (required) | String | Password of the account. |
| params (required) | Map<String, String> | Two-factor value under tfaToken or mfaSecret. |
| params.tfaToken (required) | String | Current two-factor authentication code. |
| params.mfaSecret (required) | String | Authenticator secret the SDK generates the code from. |
Returns: Call<LoginDetails>. The request for a new login session as a typed object, sent when you call execute().
Overloads
- login(String email, String password)
- login(String email, String password, Map<String, String> params)
Validation
- The three-argument overload throws IllegalArgumentException before it builds the request in the four cases below:
- email or password is empty or holds only spaces.
- params is empty.
- params holds both a tfaToken and an mfaSecret value, or neither of them.
- The SDK cannot generate a code from mfaSecret.
- The three-argument overload throws NullPointerException if email, password or params is null.
- The two-argument overload does not check its arguments.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- login builds a POST /user-session request and sends nothing until you call execute(). The body has the form {"user": {"email": "...", "password": "..."}}, plus tfa_token in the three-argument overload.
- With mfaSecret, the SDK generates the current six-digit time-based one-time password (TOTP) and sends it as tfa_token.
- execute() returns a Response<LoginDetails>. The authtoken is in response.body().getUser().getAuthtoken().
- login does not store the authtoken on the client. Requests from the client keep their current credentials.
- client.user() needs a logged-in client, so this method suits checking another account's credentials from a session that already exists. To sign the client in, use the client's login method.
Example
Basic usage: check another account's credentials
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.LoginDetails;
import retrofit2.Response;
import java.io.IOException;
public class CheckCredentials {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Response<LoginDetails> response = client.user().login(args[0], args[1]).execute();
if (!response.isSuccessful()) {
// The API rejected the login. The body holds error_message, error_code and errors.
System.out.println("Login failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println("Valid credentials for " + response.body().getUser().getEmail());
}
}All parameters: include a two-factor code
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.LoginDetails;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
public class CheckCredentialsWithTwoFactor {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Map<String, String> params = new HashMap<>();
params.put("tfaToken", "<TFA_TOKEN>");
try {
Response<LoginDetails> response = client.user().login(args[0], args[1], params).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().getNotice());
} catch (IllegalArgumentException e) {
// Thrown for an empty email or password, or invalid two-factor input
System.out.println("Invalid input: " + e.getMessage());
}
}
}logout
logout ends the session of the authtoken that the client holds, so the token stops working for every later request.
Returns: Call<ResponseBody>. The request for the logout, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- logout builds a DELETE /user-session request and sends nothing until you call execute(). The request carries the client's authtoken header.
- After a successful logout, the client still holds the old authtoken. Its requests fail with an API error, and the client's login throws IllegalStateException. Build a new client to log in again.
Warning logout ends the session for every client and script that uses the same authtoken. You cannot restore the token. Log in again to get a new one.
Example
Basic usage: end the session
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class EndSession {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Response<ResponseBody> response = client.user().logout().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}logoutWithAuthtoken
logoutWithAuthtoken ends the session of the authtoken you pass, for example a token that another process stored.
| Name | Type | Description |
|---|---|---|
| authtoken (required) | String | Authtoken of the session to end. |
Returns: Call<ResponseBody>. The request for the logout, sent when you call execute().
Validation
- There is no client-side validation. A null authtoken sends no authtoken argument, so the request works like logout.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- logoutWithAuthtoken builds a DELETE /user-session request with authtoken as a header, and sends nothing until you call execute().
- On a client that logged in, the request also carries the client's own authtoken header, so it holds two authtoken headers.
Warning logoutWithAuthtoken ends the session of the token for every client and script that uses it. You cannot restore the token.
Example
Basic usage: end a stored session
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class EndStoredSession {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Response<ResponseBody> response = client.user().logoutWithAuthtoken("<AUTHTOKEN>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}requestPassword
requestPassword asks Contentstack to email a password reset token to an account, for a user who forgot the password.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Account email, under a user key. |
| body.user.email (required) | String | Email address of the account. |
Returns: Call<ResponseBody>. The request for a password reset email, sent when you call execute().
Validation
- There is no client-side validation. requestPassword sends the body as given.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- requestPassword builds a POST /user/forgot_password request and sends nothing until you call execute().
- The response body holds a notice message. Pass the token from the email to the resetPassword method.
Example
Basic usage: request a reset email
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RequestPasswordReset {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
JSONObject fields = new JSONObject();
fields.put("email", "<EMAIL>");
JSONObject body = new JSONObject();
body.put("user", fields);
Response<ResponseBody> response = client.user().requestPassword(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}resetPassword
resetPassword sets a new password for an account with the reset token from the email that requestPassword triggers.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Reset token and new password, under a user key. |
| body.user.reset_password_token (required) | String | Token from the reset email. |
| body.user.password (required) | String | New password. |
| body.user.password_confirmation (required) | String | Same new password again. |
Returns: Call<ResponseBody>. The request for the password reset, sent when you call execute().
Validation
- There is no client-side validation. resetPassword sends the body as given.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody(). An expired or wrong token, or a password that the API does not accept, ends this way.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- resetPassword builds a POST /user/reset_password request and sends nothing until you call execute().
- The response body holds a notice message.
Warning resetPassword replaces the account password. The old password stops working, and you cannot restore it.
Example
Basic usage: set a new password
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ResetPassword {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
JSONObject fields = new JSONObject();
fields.put("reset_password_token", args[0]); // token from the reset email
fields.put("password", "<PASSWORD>");
fields.put("password_confirmation", "<PASSWORD>");
JSONObject body = new JSONObject();
body.put("user", fields);
Response<ResponseBody> response = client.user().resetPassword(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}update
update changes the profile of the logged-in account. The API changes only the fields in the body and keeps the others.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Account fields to change, under a user key. |
| body.user.first_name | String | New first name. |
| body.user.last_name | String | New last name. |
| body.user.company | String | New company name. |
Returns: Call<ResponseBody>. The request for the account update, sent when you call execute().
Validation
- There is no client-side validation. update sends the body as given.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- update builds a PUT /user request with the body and sends nothing until you call execute().
- The response body is the raw JSON with a notice message and the updated account under user.
- With setSerializeNulls off, the default, the SDK drops a key whose value is null from the body.
Example
Basic usage: change the company and last name
import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateProfile {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
JSONObject fields = new JSONObject();
fields.put("first_name", "Jane");
fields.put("last_name", "Doe");
fields.put("company", "Example Inc.");
JSONObject body = new JSONObject();
body.put("user", fields);
Response<ResponseBody> response = client.user().update(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}