Skip to main content
MindTouch Success Center

Use a server API token with an integration

This article provides instructions and examples for using your server API token in order to gain access to the MindTouch API.

Before using a server API token you will need to generate one. Review our documentation on how to generate a server API token.

What you'll need

You should have recorded the following when generating your API token:  

  • Key
  • Secret

How to use your server API token

To gain access to the MindTouch API, you first need to pass the server API token to MindTouch. Your token will be in the following format:

{key}_{epoch}_{user}_{hash}

Server API credential breakdown

key Provided with your server API token.
epoch The current time in Unix timestamp (e.g. Current time: 02/03/2015 @ 5:10am (UTC); Unix timestamp: 1422940200).
user A MindTouch user id or username prefixed with `=` (e.g. =admin). The API request will be handled in the context of this user identity.
hash MindTouch requires HMAC SHA256 hashing of server API tokens. The benefit of HMAC SHA256 over plain SHA256 is it provides MindTouch the ability to detect if the hashed token has been tampered with since being generated by your server.

The token is included in an API request by setting it on the X-Deki-Token HTTP header.

Examples

The following are code snippets for PHP, C# and Node.js to get you started:

Java example

// API Token key and secret are available from API token management dashboard when API token is generated
String key = "dacaffe7ce69dfd1071531e925f667905a1c981fb40d06c676880e84352cb3aa";
String secret = "5b70319201e9abad12a3458b32ed30cf634ef569ea47906e5012baf11cab5046";

// include username prefixed with '='
String user = '=foo';

// ...or include userid
String user = '123';

// hash time, key, user with secret
String epoch = Long.toString(new Date().getTime() / 1000L);
try {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);
    String message = key + epoch + user;

    // this example uses Apache Commons Codec (https://commons.apache.org/proper/commons-codec/) to ensure bytes are converted to a HTTP header compatible hex string
    hash = Hex.encodeHexString(sha256_HMAC.doFinal(message.getBytes()));
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
    
    // handle signing exceptions
}
String token = String.join("_", key, epoch, user, hash);

// send token as X-Deki-Token HTTP header to MindTouch API
URL url = new URL("https://success.example.com/@api/deki/pages/home/info");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("X-Deki-Token", token);

PHP example

<?php

// API Token key and secret are available from API token management dashboard when API token is generated
$key = 'dacaffe7ce69dfd1071531e925f667905a1c981fb40d06c676880e84352cb3aa';
$secret = '5b70319201e9abad12a3458b32ed30cf634ef569ea47906e5012baf11cab5046';

// include username prefixed with '='
$user = '=foo';

// ...or include userid
$user = '123';

// hash time, key, user with secret
$epoch = time(); 
$hash = hash_hmac('sha256', ($key . $epoch . $user), $secret, false);
$token = "{$key}_{$epoch}_{$user}_{$hash}";

// send token as X-Deki-Token HTTP header to MindTouch API (a fictional HTTP client is used in this example)
$client = new HttpClient('https://success.example.com/@api/deki/pages/home/info');
$client = $client->withHeader('X-Deki-Token', $token);
$response = $client->get();

C# example

// API Token key and secret are available from API token management dashboard when API token is generated
var key = "dacaffe7ce69dfd1071531e925f667905a1c981fb40d06c676880e84352cb3aa";
var secret = "5b70319201e9abad12a3458b32ed30cf634ef569ea47906e5012baf11cab5046";

// include username prefixed with '='
var user = "=foo";

// ...or include userid
user = "123";

// hash time, key, user with secret
var hash = "";
var epoch = (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds;
using(var hmac = new HMACSHA256(Encoding.ASCII.GetBytes(secret))) {
  var bytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(key + epoch + user));
  hash = BitConverter.ToString(bytes).Replace("-", "");
}
var token = string.Format("{0}_{1}_{2}_{3}", key, epoch, user, hash);

// send token as X-Deki-Token HTTP header to MindTouch API (WebRequest is used in this example)
var request = WebRequest.Create('https://success.example.com/@api/deki/pages/home/info');
request.Method = "GET";
request.Headers.Add('X-Deki-Token', token);
var response = request.GetResponse();

Node.js example

// API Token key and secret are available from API token management dashboard when API token is generated
const key = 'dacaffe7ce69dfd1071531e925f667905a1c981fb40d06c676880e84352cb3aa';
const secret = '5b70319201e9abad12a3458b32ed30cf634ef569ea47906e5012baf11cab5046';

// include username prefixed with '='
let user = '=foo';

// ...or include userid
let user = '123';

// hash time, key, user with secret
const crypto = require('crypto');
const hmac = crypto.createHmac('sha256', secret);
const epoch = Math.floor(Date.now() / 1000);
hmac.update(`${key}${epoch}${user}`);
const hash = hmac.digest('hex');
const token = `${key}_${epoch}_${user}_${hash}`;

// send token as X-Deki-Token HTTP header to MindTouch API (https://github.com/request/request is used in this example)
const request = require('request');
request({
  url: 'https://success.example.com/@api/deki/pages/home/info',
  headers: {
    'X-Deki-Token': token
  }
}, (error, response, body) => {

  // ...
});

Python 3 example

import hashlib
import hmac
import requests
import time

# API Token key and secret are available from API token management dashboard when API token is generated
key = 'dacaffe7ce69dfd1071531e925f667905a1c981fb40d06c676880e84352cb3aa'
secret = '5b70319201e9abad12a3458b32ed30cf634ef569ea47906e5012baf11cab5046'

# include username prefixed with '='
user = '=foo';

# ...or include userid
user = '123';

# hash time, key, user with secret
epoch = str(int(time.time()))
message_bytes = bytes(key + epoch + user)
secret_bytes = bytes(secret)
hash = hmac.new(secret_bytes, message_bytes, digestmod=hashlib.sha256).hexdigest().lower()
token = key + '_' + epoch_time + '_' + user + '_' + hashed_value

# send token as X-Deki-Token HTTP header to MindTouch API (Python Requests is used in this example)
headers = {
   'X-Deki-Token': apitoken,
}
r = requests.get('https://success.example.com/@api/deki/pages/home/info', headers=headers, verify=False)

Upon receipt, MindTouch calculates the same credentials and matches them to the credentials received. Once validated, your integration can access the MindTouch API.

important note   Your credentials are time sensitive. If processed too long after the time stamp is generated, your request will be denied.

  • Was this article helpful?