ManagementToken

View as Markdown

ManagementToken

A ManagementToken manages the management tokens of one stack. A management token gives read-write access to the stack content through the Content Management API (CMA), within the permissions of its scope.

Use this class to

  • list the management tokens of a stack
  • fetch the details of one management token
  • create a management token with stack-level permissions and an expiry date
  • update or delete a management token

addHeader

addHeader adds one header to every request of this management token object.

NameTypeDescription
key (required)String

Name of the header, for example authtoken.

Default: Not applicable
value (required)String

Value to send in the header.

Default: Not applicable

Returns: ManagementToken. The same management token object, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addHeader stores the pair in the object's header map and sends no request.
  • Every request method of the object sends the header: find, fetch, create, update and delete.
  • A second call with the same key replaces the value. A key that the stack already set, such as api_key, takes the new value for this object only.
  • The header does not reach the stack or other token objects.

Example

Basic usage: send an authtoken that you already hold

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ManagementTokensWithAuthtoken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>");
        // The client did not log in, so pass the authtoken as a header
        ManagementToken managementTokens = stack.tokens().managementToken().addHeader("authtoken", "<AUTHTOKEN>");

        Response<ResponseBody> response = managementTokens.find().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());
    }
}

addHeaders

addHeaders adds several headers to every request of this management token object.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

Returns: ManagementToken. The same management token object, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addHeaders copies every entry into the object's header map and sends no request.
  • Every request method of the object sends the headers: find, fetch, create, update and delete.
  • An entry whose name already exists replaces the earlier value. Headers that the map does not name stay unchanged.

Example

Basic usage: send an authtoken from a header map

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class ManagementTokensWithHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>");
        HashMap<String, String> headers = new HashMap<>();
        headers.put("authtoken", "<AUTHTOKEN>");
        ManagementToken managementTokens = stack.tokens().managementToken().addHeaders(headers);

        Response<ResponseBody> response = managementTokens.find().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());
    }
}

addParam

addParam adds one query parameter to the find request of this management token object.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter.

Default: Not applicable

Returns: ManagementToken. The same management token object, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addParam stores the pair in the object's query parameter map and sends no request.
  • Only find sends the map. fetch, create, update and delete send no query parameters.
  • A second value for the same name replaces the earlier one. The value stays on the object for every later find. Use the removeParam method to drop it.
  • The Get all management tokens reference lists no query parameters, so the API decides what to do with each value you send.

Example

Basic usage: see the parameter on the find request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;

public class ManagementTokenFindParam {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementTokens = stack.tokens().managementToken().addParam("include_count", true);

        // request() builds the request without sending it. The URL carries include_count=true.
        System.out.println(managementTokens.find().request().url());
    }
}

addParams

addParams adds several query parameters to the find request of this management token object.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

Returns: ManagementToken. The same management token object, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addParams stores the entries in the object's query parameter map and sends no request.
  • Only find sends the map. fetch, create, update and delete send no query parameters.
  • A second value for the same name replaces the earlier one. The value stays on the object for every later find. Use the removeParam method to drop it.
  • The Get all management tokens reference lists no query parameters, so the API decides what to do with each value you send.

Example

Basic usage: see the parameters on the find request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;

import java.util.HashMap;

public class ManagementTokenFindParams {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>");
        HashMap<String, Object> params = new HashMap<>();
        params.put("include_count", true);
        ManagementToken managementTokens = stack.tokens().managementToken().addParams(params);

        // request() builds the request without sending it. The URL carries the parameters.
        System.out.println(managementTokens.find().request().url());
    }
}

create

create builds the request that creates a management token in the stack.

NameTypeDescription
requestBody (required)JSONObject

Token details in a token object, for example name, scope and expires_on.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the new management token, sent when you call execute().

Validation

  • There is no client-side validation. create sends requestBody unchanged.
  • The API rejects the request unless the logged-in user is the owner or an admin of the stack. Only these users can generate a management token, as the API reference states.
  • 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

  • One execute() sends one Create management token request (POST /stacks/management_tokens) with the object's headers and requestBody as the JSON body.
  • The API reference names four details of the token: its name, its description, the stack-level permissions of its scope, and an optional expiry date.
  • The expiry date is in Coordinated Universal Time (UTC). You can also ask for an email notification seven days before the token expires.
  • create sends no query parameters and ignores the UID of the object.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: create a management token for content types on one branch

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class CreateManagementToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        JSONObject readWrite = new JSONObject();
        readWrite.put("read", true);
        readWrite.put("write", true);
        JSONObject contentTypeScope = new JSONObject();
        contentTypeScope.put("module", "content_type");
        contentTypeScope.put("acl", readWrite);

        JSONObject read = new JSONObject();
        read.put("read", true);
        JSONArray branches = new JSONArray();
        branches.add("<BRANCH>");
        JSONObject branchScope = new JSONObject();
        branchScope.put("module", "branch");
        branchScope.put("branches", branches);
        branchScope.put("acl", read);

        JSONArray scope = new JSONArray();
        scope.add(contentTypeScope);
        scope.add(branchScope);

        JSONObject token = new JSONObject();
        token.put("name", "docs-test-management-token");
        token.put("description", "Reads and writes content types");
        token.put("scope", scope);
        token.put("expires_on", "2027-12-31");
        token.put("is_email_notification_enabled", true);
        JSONObject body = new JSONObject();
        body.put("token", token);

        Response<ResponseBody> response = stack.tokens().managementToken().create(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());
    }
}

delete

delete builds the request that deletes one management token.

Returns: Call<ResponseBody>. The request for the management token deletion, sent when you call execute().

Validation

  • Throws IllegalAccessError if the object holds no UID or an empty one, as from managementToken(), because delete works on one token by its UID. IllegalAccessError is an Error, so catch (Exception e) does not catch 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

  • One execute() sends one Delete management token request (DELETE /stacks/management_tokens/{token_uid}) with the object's headers.
  • delete sends no query parameters.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: delete a management token

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class DeleteManagementToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementToken = stack.tokens().managementToken("<TOKEN_UID>");

        Response<ResponseBody> response = managementToken.delete().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());
    }
}

fetch

fetch builds the request that retrieves the details of one management token.

Returns: Call<ResponseBody>. The request for the management token, sent when you call execute().

Validation

  • Throws IllegalAccessError if the object holds no UID or an empty one, as from managementToken(), because fetch works on one token by its UID. IllegalAccessError is an Error, so catch (Exception e) does not catch 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

  • One execute() sends one Get a single management token request (GET /stacks/management_tokens/{token_uid}) with the object's headers.
  • The API returns the details of the token, not the token value.
  • fetch sends no query parameters.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: fetch one management token

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchOneManagementToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementToken = stack.tokens().managementToken("<TOKEN_UID>");

        Response<ResponseBody> response = managementToken.fetch().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());
    }
}

Edge case: catch the missing UID error

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchManagementTokenWithoutUid {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementTokens = stack.tokens().managementToken();

        try {
            Response<ResponseBody> response = managementTokens.fetch().execute();
            if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
            System.out.println(response.body().string());
        } catch (IllegalAccessError error) {
            // Fires because the object holds no token UID. The SDK sent no request.
            System.out.println("Open the token with managementToken(\"<TOKEN_UID>\") first.");
        }
    }
}

find

find builds the request that lists every management token of the stack.

Returns: Call<ResponseBody>. The request for all management tokens of the stack, 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

  • One execute() sends one Get all management tokens request (GET /stacks/management_tokens) with the object's headers and its query parameters.
  • The API returns the details of each token, not the token values.
  • find ignores the UID of the object, so it lists every token from either kind of ManagementToken.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: list the management tokens of a stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListManagementTokenDetails {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementTokens = stack.tokens().managementToken();

        Response<ResponseBody> response = managementTokens.find().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());
    }
}

removeParam

removeParam removes one query parameter from this management token object, so later find requests no longer send it.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • There is no client-side validation. A key that the object does not hold changes nothing and raises no error.

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

Behavior

  • Client-side only. removeParam deletes the entry from the object's query parameter map and sends no request.
  • removeParam returns nothing, so it ends a chain. Call it as a separate statement.
  • The removal affects later calls to find only, because no other request of the class sends query parameters.

Example

Basic usage: drop a parameter before the next request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ManagementToken;
import com.contentstack.cms.stack.Stack;

public class RemoveManagementTokenParam {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>");
        ManagementToken managementTokens = stack.tokens().managementToken().addParam("include_count", true);
        managementTokens.removeParam("include_count");

        // request() builds the request without sending it. The URL has no query string.
        System.out.println(managementTokens.find().request().url());
    }
}

update

update builds the request that updates the name, description, permissions or expiry date of one management token.

NameTypeDescription
requestBody (required)JSONObject

Updated token details in a token object, for example name, scope and expires_on.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the updated management token, sent when you call execute().

Validation

  • Throws IllegalAccessError if the object holds no UID or an empty one, as from managementToken(), because update works on one token by its UID. IllegalAccessError is an Error, so catch (Exception e) does not catch 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

  • One execute() sends one Update management token request (PUT /stacks/management_tokens/{token_uid}) with the object's headers and requestBody as the JSON body.
  • The API reference names the fields you can change: the name, the description, the stack-level permissions and the branch and alias scope.
  • You can also change the expiry date, if the token has one.
  • update sends no query parameters.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: rename a management token and change its permissions

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class UpdateManagementToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");
        JSONObject readWrite = new JSONObject();
        readWrite.put("read", true);
        readWrite.put("write", true);
        JSONObject contentTypeScope = new JSONObject();
        contentTypeScope.put("module", "content_type");
        contentTypeScope.put("acl", readWrite);

        JSONObject read = new JSONObject();
        read.put("read", true);
        JSONArray branches = new JSONArray();
        branches.add("<BRANCH>");
        JSONObject branchScope = new JSONObject();
        branchScope.put("module", "branch");
        branchScope.put("branches", branches);
        branchScope.put("acl", read);

        JSONArray scope = new JSONArray();
        scope.add(contentTypeScope);
        scope.add(branchScope);

        JSONObject token = new JSONObject();
        token.put("name", "docs-test-management-token-renamed");
        token.put("description", "Reads and writes content types");
        token.put("scope", scope);
        token.put("expires_on", "2027-12-31");
        token.put("is_email_notification_enabled", true);
        JSONObject body = new JSONObject();
        body.put("token", token);

        Response<ResponseBody> response = stack.tokens().managementToken("<TOKEN_UID>").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());
    }
}