Public API v1 → Create Token Endpoint

About the /tokens endpoint

When requesting your initial access and refresh tokens, you will access the /tokens endpoint with a POST request. Access tokens allow request access to other API endpoints. A refresh token is paired with your access token, and is used in the /refresh endpoint to obtain new access and refresh tokens. Subsequent requests for a refreshed access token will use the /refresh endpoint.

For information about how to get started with Public API v1, refer to References → Public API v1.

For information about how to refresh an access token, refer to Public API v1 → Refresh Token Endpoint.

Request URL

Use one of the following URLs to call the /tokens endpoint.

• https://<cluster_URL>/incorta/api/v1/tokens
• https://<server address>:<port>/incorta/api/v1/tokens

Request body

Following is a json template of a /tokens endpoint request:

Copy
{
  "tenantName": "string",
  "loginName": "string",
  "requestHash": "string",
  "timestamp": number
}

tenantName: String value of the user’s tenant

loginName: String value of the user login name.

requestHash: A concatenated hex string, using the sha256 hashing algorithm, of the API Key and the request epoch timestamp in milliseconds.

timestamp: The request epoch timestamp in milliseconds

Creating a requestHash and timestamp

The following are simple example code snippets for creating your timestamp and requestHash values. Be aware that the syntax and methods used may vary depending on your language version.

Python version: 3.5

Copy
import hashlib
import time
import calendar
# Create the epoch millisecond timestamp
timestamp = calendar.timegm(time.gmtime()) * 1000

# Enter the user API key as a string
api_key = "<Your API key>"

# Concatenate the api_key and timestamp strings
request = (api_key + str(timestamp)).encode('utf-8')

# Generate the request hash string
request_hash = hashlib.sha256(request).hexdigest()

print (f"The epoch timestamp in milliseconds is: {timestamp}")
print ("The sha256 request hash is: " + request_hash)

Javascript version ES8

Copy
async function digestMessage(message) {
    // Encode as UTF-8
    const msgBuffer = new TextEncoder().encode(message);                    

    // Hash the message
    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);

    // Convert ArrayBuffer to Array
    const hashArray = Array.from(new Uint8Array(hashBuffer));

    // Convert bytes to hex string                  
    const hashHex = hashArray.map(b => ('00' + b.toString(16)).slice(-2)).join('');
    console.log("The request hash is: " + hashHex);
}

// Create timestamp
const timestamp = Date.now();
// The user API key as string
const api_key = "<Your API Key>";
// Concatenate the api_key and timestamp
const request = api_key + timestamp;

console.log( "The epoch timestamp in milliseconds is: " + timestamp );
digestMessage(request);

Java version 11

Copy
import java.time.Instant;
import java.security.MessageDigest;

public class Main {
    public static void main(String args[]) {
        // Create the epoch timestamp string in milliseconds
        String timestamp = Long.toString(Instant.now().toEpochMilli());
        System.out.println("The epoch timestamp is: " + timestamp);


        // The user API key as a string
        String api_key = "<Your API Key>";
        // Concatenate the api_key and timestamp strings
        String request = api_key + timestamp;


        // Generate the requestHash string
        String request_hash = sha256(request);  

        System.out.println(request_hash);
  }

    // Sha256 hashing function
    public static String sha256(String base) {
    try{
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(base.getBytes("UTF-8"));
        StringBuffer hexString = new StringBuffer();

        for (int i = 0; i < hash.length; i++) {
            String hex = Integer.toHexString(0xff & hash[i]);
            if(hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }

        return hexString.toString();
    } catch(Exception ex){
       throw new RuntimeException(ex);
    }
}
}

C# version: 4.0

Copy
using System;
using System.Security.Cryptography;
using System.Text;

public class Program {
    public static void Main(string[] args) {
        // Get the current timestamp
        DateTimeOffset now = DateTimeOffset.UtcNow;

        // Convert the timestamp to Unix epoch in milliseconds
        string timestamp = now.ToUnixTimeMilliseconds().ToString();
        Console.WriteLine("The epoch timestamp is: " + timestamp);

        // The user API key as a string
        string api_key = "<Your API Key>";

        // Concatenate the api_key and timestamp strings
        string request = api_key + timestamp;


       // Generate the request hash string
       using (SHA256 sha256Hash = SHA256.Create())
        {
            string hash = GetHash(sha256Hash, request);
            Console.WriteLine("The SHA256 request hash is: " + hash);
        }


    }


    private static string GetHash(HashAlgorithm hashAlgorithm, string input)
    {

        // Convert the input string to a byte array and compute the hash.
        byte[] data = hashAlgorithm.ComputeHash(Encoding.UTF8.GetBytes(input));

        // Create a new Stringbuilder to collect the bytes
        // and create a string.
        var sBuilder = new StringBuilder();

        // Loop through each byte of the hashed data
        // and format each one as a hexadecimal string.
        for (int i = 0; i < data.Length; i++)
        {
            sBuilder.Append(data[i].ToString("x2"));
        }

        // Return the hexadecimal string.
        return sBuilder.ToString();
    }
}

Request hash alternatives

Instead of using a programmatic solution to generate your request hash, you can use resources available online. A site such as currentmillis can be used to get your current timestamp in milliseconds. A hash converter such as emn178.github.io can be used to encode your API key and timestamp. Any generated request hash will always expire 30 minutes after being generated.

Endpoint response

The /tokens endpoint has five possible response codes and payloads.

Endpoint 201 response

Copy
{
  "accessToken": "string",  
  "refreshToken": "string",
  "type": "string",  
  "accessTokenExpiresAt": number,  
  "refreshTokenExpiresAt": number
}