How to get the authorization header for accessing Cosmos DB REST API by using Java

All Cosmos DB REST operations, whether you’re using a master key token or resource token, must include the authorization header with the authorization string in order to interact with a resource. This article will show you how to get the authorization header by using  Java.

The authorization string has the following format:


{typeoftoken} denotes the type of token: master or resource.

{tokenversion} denotes the version of the token, currently 1.0.

{hashsignature} denotes the hashed token signature.

I will use “master” for typeoftoken and “1.0” for tokenversion. The key part is hashsignature. So let us see how to get the hashsignature. The hash signature for the master key token can be constructed from the following parameters: VerbResourceTypeResourceLink and Date.

  1. The Verb portion of the string is the HTTP verb, such as GET, POST or PUT.
  2. The ResourceType portion of the string identifies the type of resource that the request is for, Eg. “dbs”, “colls”, “docs”.
  3. The ResourceLink portion of the string is the identity property of the resource that the request is directed at. ResourceLink must maintain its case for the id of the resource. Example, for a collection it will look like: “dbs/MyDatabase/colls/MyCollection”.
  4. The Date portion of the string is the UTC date and time the message was sent e.g. Tue, 01 Nov 1994 08:12:31 GMT.

The authorization string should be encoded before adding it to the REST request to ensure that it contains no invalid characters.To encode the signature string for a request against Cosmos DB, use the following format:

StringToSign = Verb.toLowerCase() + "\n" + ResourceType.toLowerCase() + "\n" + ResourceLink + "\n" + Date.toLowerCase() + "\n" + "" + "\n";

Here I want to call ‘create container’ Rest API, so I can get the authorization header like this:

 String verb="POST";
 String resourceType="colls";
 String resourceId = "dbs/db";
 String date=DateTimeFormatter.RFC_1123_DATE_TIME.format("GMT")));
 String key="qwQ54zuR7nVyHibeBWNyxnD9yDHjmAvthSzmBTXXXp8OR0evcjqD3DBCGJuNacDV4hJwVeXk9VV2CPYyq2ZOQ==";
 String keyType = "master";
 String tokenVersion = "1.0";
 String payload=verb.toLowerCase()+"\n"
 Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
 SecretKeySpec secret_key = new SecretKeySpec(Base64.getDecoder().decode(key), "HmacSHA256");
 String signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(payload.getBytes("UTF-8")));
 String authorization=URLEncoder.encode("type="+keyType+"&ver="+tokenVersion+"&sig="+signature, "utf-8");

We will get the authorization string from the console. It looks like


Now let us test if the  authorization string we get is useful. I will use Restlet Client to test the Rest API. The screenshot is as below.

The response code is 201, we have called the ‘create container’ Rest API successfully. It indicates that the authorization header works. We can find the container which called col4 in the portal.

If you have other concerns, please contact us via

Leave a Reply

Your email address will not be published. Required fields are marked *