Skip to main content
MindTouch Success Center

Implement Custom SSO With the API (Legacy)

Applies to:
MindTouch TCS & 4 (legacy)
Role required:

DEPRECATED! This authentication method is no longer a recommended or supported approach. MindTouch recommends using OpenID Connect or SAML SSO, which provides enterprise-grade authentication security. If a custom solution is absolutely required, a server API token can used to authenticate using the steps outlined in this article.

Enable single sign-on between MindTouch and another authentication system. MindTouch supports signing in via a redirect from your SSO portal or application. Create an impersonation authentication token to generate the impersonation authentication token parameter required in the sign-in redirect URI.

Sign-On via Redirect

The redirect method is useful when you want to log the user in when the user clicks a link to the MindTouch site. Using an impersonation authentication token, you can construct a URI that logs the user in and redirects to any page in MindTouch. To tell the API to issue a cookie, use the following format to create a URI for the user to follow:

GET http://SERVER/@api/deki/users/authenticate?authtoken=IMPAUTHTOKEN&redirect=REDIRECT


  • IMPAUTHTOKEN is the  impersonation authentication token
  • SERVER is the hostname of your MindTouch site
  • REDIRECT is a URI for the user to be redirected to (e.g. redirect=http://SERVER/). This URI must be URI encoded

Since this URI is valid for only about 60 seconds, 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/
X-Deki-Site: id="SITE"
X-Deki-Session: SESSION
Content-Type: text/plain; charset=us-ascii
Content-Length: 20
Set-Cookie: authtoken="AUTHTOKEN"; Domain=.SERVER;
Set-Cookie: dekisession="SESSION"; Domain=.SERVER;

This results in a sign-on 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 impersonation token 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 authenticated cookie and the Location Header for REDIRECT.

It is not possible to log the user out via your authentication system. The user must manually log out via the MindTouch site.

Sign-On by Forwarding Cookie in the Same Parent Domain

Forwarding the cookies issued by MindTouch from the users/authenticate API call allows your authentication system to handle logging in and/or creating the user's MindTouch account upon sign in.

The primary limitation of this method is that the MindTouch hostname must be in the same parent domain as the authentication system. For example, if the site that is responsible for the authentication is, then your MindTouch hostname must also include *

To log the user in to the MindTouch site, you must make a GET request to

GET http://SERVER/@api/deki/users/authenticate?authtoken=IMPAUTHTOKEN


A successful request will result in an HTTP response similar to the following:

HTTP/1.1 200 OK
Date: Thu, 25 Sep 2014 22:34:56 GMT
Server: Dream-HTTPAPI/
X-Deki-Site: id="SITE_ID"
X-Deki-Session: SESSION
Content-Type: text/plain; charset=utf-8
Content-Length: 85
Set-Cookie: authtoken="AUTHTOKEN"; Domain=.SERVER
Set-Cookie: secureauthtoken="true"; Domain=.SERVER
Set-Cookie: dekisession="SESSION"; Domain=.SERVER
Vary: Accept-Encoding
Connection: close


You can forward the Set-Cookie headers to your customer, which will set them on the customer browser so they will be already authenticated when they visit your MindTouch site.

This results in the following sign-on workflow:

  1. End-user logs in to your authentication system.
  2. Your authentication system builds above URI and impersonation token, and sends a request to the MindTouch site.
  3. Your authentication system forwards the Set-Cookie headers from the MindTouch authentication response to the End-user.
  4. If the user exists in MindTouch, the user is logged in to both your authentication system and MindTouch.
  5. If the user does not exist in MindTouch, the user is created as a Community Member.

To automatically log the user out of the MindTouch site, your authentication system needs to issue a Set-Cookie header to remove the authtoken and dekisession cookies.

The authtoken issued by MindTouch is valid for 6.5 days by default, but you can contact Customer Support to set a custom expiration time. Alternately, you can shorten the authtoken expiration with a cookie expiration time. You cannot extend the expiration with a cookie expiration time. If your authentication system timeout is longer than the authtoken timeout, it's possible a user can still be logged into your system without being logged in to MindTouch.

Create an Impersonation Authentication Token

Impersonation is a way for the holder of the API key to access MindTouch as a user. This token can be used on individual requests or with the authentication API call to issue a new authentication cookie. The format of the impersonation token is:



  • TIMESTAMP is the issue time for the auth token in Unix epoch in UTC. This prevents the same token from being captured and the request replayed at a later time. Timestamp must be within 1 minute of server time to be valid.
  • AUTHHASH is an MD5 hash of this UTF8 string: USERNAME:TIMESTAMP:APIKEY
  • USERNAME is the user's log-in name.
  • APIKEY is the instance API key for your MindTouch, with all letters in lowercase.

The AUTHHASH must be lowercase for the connection to be valid.

Code samples


public void sample() throws NoSuchAlgorithmException, UnsupportedEncodingException {
    String apikey = "123abc";
    String username = "foo";
    String timestamp = String.valueOf(System.currentTimeMillis()/1000);

    // hash the values as "username:timestamp:apikey"
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    String textToHash = String.format("%s:%s:%s", username, timestamp, apikey);

    // it is highly recommended Java programmers use the superior Apache Commons Codec library
    // for MD5 hashing.
    String hash = DigestUtils.md5Hex(textToHash);
    // create the token
    String impersonationToken = String.format("imp_%s_%s_=%s", timestamp, hash, username);
    // depending on your HTTP client, you may or may not need to URL encode the token
    impersonationToken = URLEncoder.encode(impersonationToken, "UTF-8")


$apikey = '123abc';
$username = 'foo';
$timestamp = time();

// create the MD5 AUTHHASH 
$auth_hash = md5("{$username}:{$timestamp}:{$apikey}");

// create the token
$imp_auth_token = "imp_{$timestamp}_{$auth_hash}_={$username}";

// depending on your HTTP client, you may or may not need to URL encode the token
$imp_auth_token = urlencode($imp_auth_token);

Implementation Notes

Impersonation tokens are only valid for a short time period, and shouldn't be printed in the page itself. Instead, generate the authentication link dynamically, after the user clicks a help link in your application. For example, a help link might be<somearticle>, where the SSO page generates the token and redirects the user.

  • Was this article helpful?