User

View as Markdown

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.

NameTypeDescription
activationToken (required)String

Token from the activation URL in the sign-up email.

Default: Not applicable
body (required)JSONObject

Account details, under a user key.

Default: Not applicable
body.user.first_name (required)String

First name of the account.

Default: Not applicable
body.user.last_name (required)String

Last name of the account.

Default: Not applicable
body.user.password (required)String

Password to set.

Default: Not applicable
body.user.password_confirmation (required)String

Same password again.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Header name.

Default: Not applicable
value (required)String

Header value.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap

Header names and values.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Query parameter name.

Default: Not applicable
value (required)Object

Query parameter value.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap

Query parameter names and values.

Default: Not applicable

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.

NameTypeDescription
email (required)String

Email address of the Contentstack account.

Default: Not applicable
password (required)String

Password of the account.

Default: Not applicable
params (required)Map<String, String>

Two-factor value under tfaToken or mfaSecret.

Default: Not applicable
params.tfaToken (required)String

Current two-factor authentication code.

Default: Not applicable
params.mfaSecret (required)String

Authenticator secret the SDK generates the code from.

Default: Not applicable

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.

NameTypeDescription
authtoken (required)String

Authtoken of the session to end.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Account email, under a user key.

Default: Not applicable
body.user.email (required)String

Email address of the account.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Reset token and new password, under a user key.

Default: Not applicable
body.user.reset_password_token (required)String

Token from the reset email.

Default: Not applicable
body.user.password (required)String

New password.

Default: Not applicable
body.user.password_confirmation (required)String

Same new password again.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Account fields to change, under a user key.

Default: Not applicable
body.user.first_nameString

New first name.

Default: Not applicable
body.user.last_nameString

New last name.

Default: Not applicable
body.user.companyString

New company name.

Default: Not applicable

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());
    }
}