Tokens

View as Markdown

Tokens

A Tokens object opens the delivery tokens and management tokens of a stack. A delivery token gives read-only access to the published content of an environment through the Content Delivery API. A management token gives read-write access to the stack content through the Content Management API (CMA).

Use this class to

  • open the delivery tokens of a stack, to list, create, update or delete them
  • open the management tokens of a stack, to list, create, update or delete them

deliveryTokens

deliveryTokens creates a DeliveryToken object for one delivery token, or for all the delivery tokens of the stack.

NameTypeDescription
tokenUid (required)String

UID of the delivery token to open.

Default: Not applicable

Returns: DeliveryToken. A new delivery token object.

Overloads

  • deliveryTokens(String tokenUid)
  • deliveryTokens(): This overload takes no parameters. Call find or create on the result.

Validation

  • There is no client-side validation. deliveryTokens accepts null and an empty string, despite the @NotNull annotation.
  • Errors that do occur come from the request method you call on the result, not from deliveryTokens().
    • fetch, update and delete() throw NullPointerException before any request if the object holds no UID, because they work on one token. A DeliveryToken from deliveryTokens() holds no UID, so call find or create on it instead.
    • An unknown UID surfaces as an API error in the response of fetch, update or delete.

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

Behavior

  • Client-side only. deliveryTokens sends no request.
  • Each call returns a new DeliveryToken with a copy of the current stack headers.
  • deliveryTokens("<TOKEN_UID>") leads to fetch, update and delete. fetch sends the Get a single delivery token request.
  • deliveryTokens() leads to find and create. find sends the Get all delivery tokens request.

Example

Basic usage: fetch one delivery token

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

import java.io.IOException;

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

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

List every delivery token of the stack

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

import java.io.IOException;

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

        Response<ResponseBody> response = deliveryTokens.find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

managementToken

managementToken creates a ManagementToken object for one management token, or for all the management tokens of the stack.

NameTypeDescription
managementTokenUid (required)String

UID of the management token to open.

Default: Not applicable

Returns: ManagementToken. A new management token object.

Overloads

  • managementToken(String managementTokenUid)
  • managementToken(): This overload takes no parameters. Call find or create on the result.

Validation

  • There is no client-side validation. managementToken accepts null and an empty string, despite the @NotNull annotation.
  • Errors that do occur come from the request method you call on the result, not from managementToken().
    • fetch, update and delete throw IllegalAccessError before any request if the object holds no UID or an empty one, because they work on one token. A ManagementToken from managementToken() holds no UID, so call find or create on it instead.
    • An unknown UID surfaces as an API error in the response of fetch, update or delete.

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

Behavior

  • Client-side only. managementToken sends no request.
  • Each call returns a new ManagementToken with a copy of the current stack headers.
  • managementToken("<TOKEN_UID>") leads to fetch, update and delete. fetch sends the Get a single management token request.
  • managementToken() leads to find and create. find sends the Get all management tokens request.

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

List every management token of the 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 ListManagementTokens {
    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()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}