Skip to main content
MindTouch Success Center

Use a server API token with an integration

Instructions and examples to validate your server API token in order to gain access to the MindTouch API.

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 a server API token signature to MindTouch. Your token signature will be in the following format:

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

Server API token signature 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 token signature has been tampered with since being generated by your server.

The token signature is included in an API request by setting the value in the X-Deki-Token HTTP header. Upon receipt, MindTouch calculates the same signature and matches it to the signature received. Once validated, your integration can access the MindTouch API.

Your signature is time sensitive. If processed too long after the timestamp is generated, your request will be denied.

Examples

The following are code snippets for PHP, C#, Node.js, and Python 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("_", "tkn", key, epoch, user, hash);

// send signature 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 = "tkn_{$key}_{$epoch}_{$user}_{$hash}";

// send signature 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(string.Format("{0}_{1}_{2}", key, epoch, user)));
  hash = BitConverter.ToString(bytes).Replace("-", "");
}
var token = string.Format("tkn_{0}_{1}_{2}_{3}", key, epoch, user, hash);

// send signature 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 = `tkn_${key}_${epoch}_${user}_${hash}`;

// send signature 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 = 'tkn_' + key + '_' + epoch_time + '_' + user + '_' + hashed_value

# send signature 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)

Authenticate with a server API token

A server API token signature can be traded for an Auth Token session cookie, which will sign in a user. Using this method, you can construct a URI that logs the user in and redirects to any page in MindTouch. To tell the API to issue an Auth Token session cookie, use the following format to create a URI for the user to follow:

GET http://{hostname}/@api/deki/users/authenticate?x-deki-token={signature}&redirect={redirect}
  • {hostname} is the hostname of the MindTouch site
  • {signature} is the server API token signature
  • {redirect} is a URI for the user to be redirected to (e.g. redirect=https://example.com/foo). This URI must be URI encoded

Since this URI is valid for only a few minutes, it should not be generated as a URI on one of your pages directly. Instead, it should be a redirect response of a request to your server that authenticates the user in your system. The system should build the URI at the time of request. After the user follows the URI, if the authentication is successful they receive HTTP response headers similar to the following:

HTTP/1.1 302 FOUND
Date: Thu, 28 Feb 2013 19:58:59 GMT
Server: Dream-HTTPAPI/2.4.0.393
X-Deki-Site: id="{site}"
X-Deki-Session: {session}
Content-Type: text/plain; charset=us-ascii
Content-Length: 20
Location: {redirect}
Set-Cookie: authtoken="{authtoken}"; Domain=.{hostname};
Set-Cookie: dekisession="{session}"; Domain=.{hostname};

This results in a sign in workflow like this:

  1. A user logged into your authentication system clicks a URI to go to the MindTouch site. Note: the URL actually points to an endpoint on your site.
  2. Your endpoint validates the user's credentials.
  3. Your endpoint constructs the server API token signature and the redirect URI above.
  4. Your endpoint responds with a 302 Found response and the constructed URI as its Location Header.
  5. The user's browser redirects to the MindTouch API.
  6. The MindTouch API creates the user as a Community Member if they do not exist on MindTouch site, and issues a 302 Found response including the Auth Token session cookie and the Location Header for {redirect}.
  • Was this article helpful?