ManagementToken
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, for example authtoken. |
| value (required) | String | Value to send in the header. |
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.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter. |
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.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Token details in a token object, for example name, scope and expires_on. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
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.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Updated token details in a token object, for example name, scope and expires_on. |
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());
}
}