Use a Server API Token With an Integration

Server API Token Signature Breakdown

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

Java Example

// Server API Token key and secret are available from API token management dashboard when Server API Token is generated
String key = "REPLACE_KEY";
String secret = "REPLACE_SECRET";

// 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

// Server API Token key and secret are available from API token management dashboard when Server API Token is generated
$key = 'REPLACE_KEY';
$secret = 'REPLACE_SECRET';

// 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

using System;
using System.IO;
using System.Security.Cryptography;
using System.Net.Http;

// Server API Token key and secret are available from API token management dashboard when Server API Token is generated
var key = "REPLACE_KEY";
var secret = "REPLACE_SECRET";

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

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

// 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 signature = 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 client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Deki-Token", signature);
var response = await client.GetAsync("https://authtalk.mindtouch.es/@api/deki/users/current?dream.out.format=json");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

// Exchange signature token for a user's authtoken for immediate access via a link.
// https://{authtalk.mindtouch.es}/@api/deki/users/authenticate?x-deki-token={signature}
Console.WriteLine($"https://authtalk.mindtouch.es/@api/deki/users/authenticate?x-deki-token={signature}");

Console.WriteLine($"https://authtalk.mindtouch.es/@api/deki/users/authenticate?x-deki-token={signature}&redirect=https%3A%2F%2Fauthtalk.mindtouch.es%2F");

Node.js Example

// Server API Token key and secret are available from API token management dashboard when Server API Token is generated
const key = 'REPLACE_KEY';
const secret = 'REPLACE_SECRET';

// 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 time
import requests
import hmac

# Server API Token key and secret are available from API token management dashboard when Server API Token is generated
key = 'REPLACE_KEY'
secret = 'REPLACE_SECRET'

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

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

# hash time, key, user with secret
epoch = str(int(time.time()))
message_bytes = f'{key}_{epoch}_{user}'.encode('utf-8')
secret_bytes = secret.encode('utf-8')
hash = hmac.new(secret_bytes, message_bytes, digestmod=hashlib.sha256).hexdigest().lower()
token = f'tkn_{key}_{epoch}_{user}_{hash}'

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

# Handling the response
if response.status_code == 200:
    # Success
    print(response.text)
else:
    # Error
    print(f"Error: {response.status_code} - {response.text}")

Postman Example

In pre-request script:

// Server API Token key and secret are available from API token management dashboard when Server API Token is generated
const key = 'REPLACE_KEY';
const secret = 'REPLACE_SECRET';

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

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

const epoch = Math.floor(Date.now() / 1000);
var hash = CryptoJS.HmacSHA256(`${key}_${epoch}_${user}`, secret);
const token = `tkn_${key}_${epoch}_${user}_${hash}`;
pm.request.headers.add({
    key: 'x-deki-token',
    value: token
});