Auto Login to Teapplix

One of the benefits of setting up "paired account" is that Partner's user can click on a single link or button from partner system, and login to Teapplix web application without entering username + password. This is achieved using the PSObtainToken API call and upon success, going to a specific "LaunchURL" afterwards.

PSObtainToken

From partner system, you will call this API to obtain the parameters needed to open a Teapplix application without login. This application should normally be opened in a separate browser tab:

Request to this method is done via HTTP GET:
https://api.teapplix.com/api2/PSObtainToken?PSClientID=xxxxxxx

Here is the work flow:

1. Call PSObtainToken
2. Open browser tab to Launch URL, Launch URL is like this:
   https://app.teapplix.com/h/[ClientVHOST]/te/lo.cgi?Action=Launch&pt=[AccessToken]&ts=[unixtimestamp]&signature=[signedstringvalue]
3. ClientVHOST - is returned in PSObtainToken response
4. Check next section for samples how to calculate signature=signedstringvalue
5. Note, that issued temporary access token will expire in 30 minutes, if not used

Please, not that this method is protected and you need to specify APIToken HTTP-header in request, as well as for any other protected API method.

Request/Response details:

Launch URL

Launch URL is used as start point for UI for Partner's customer to go to Teapplix web applicatin.
This URL makes authentication, so that there is not need to enter login/password values and user can "jump" directly to his UI.

Base host is: https://app.teapplix.com/
URI and options are next:

Base URI: /h/ClientVHOST/te/lo.cgi?Action=Launch

• ClientVHOST

This value is returned from PSObtainToken, it indicate the matching Teapplix Account Name.

• pt=AccessToken

Result of ObtainAccessToken API method call

• ts=unixtimestamp

unixtimestamp is integer value of UNIX epoch, for example: 1483257600

• signature=signedstringvalue

Signature Key

Signature key is based on Partner. Typically, we use the "Token" from Partner's system, entered to a specific Teapplix account to allow Teapplix account to access Partner system, as the Signature Key. Signature Key is not passed as a parameter to the Teapplix API call, nor is it passed as part of the LaunchURL. However, it is internally used to compute and validate the LaunchURL.

• Signature

Signature is parameter which is sent in "launch URL". It should be calculated based on next scheme:
hmac(sha256(uri), Signature Key).asHexValue().

"URI" is full uri with options (for example: /h/demo2/te/lo.cgi?Action=Launch&pt=AccessToken&ts=unixtimestamp)

After signature was calculated, result value should be added to uri and result URI is address which user's browser should be redirected to.

/h/demo2/te/lo.cgi?Action=Launch&pt=AccessToken&ts=unixtimestamp&signature=a19fe6204cb34767f48260719c4f25a9ae5e966e8

Samples of implementation:

• Perl

use Digest::SHA qw(hmac_sha256_hex);
my $options = '/h/demo2/te/lo.cgi?Action=Launch&pt=AccessToken&ts=unixtimestamp';
my $signature = hmac_sha256_hex($options, 'Signature Key');
my $url = $options . '&signature=' . $signature;

• PHP

$options = '/h/demo2/te/lo.cgi?Action=Launch&pt=AccessToken&ts=unixtimestamp';
$signature = hash_hmac('sha256', $options, 'Signature Key', false);
$signedURL = $options . '&signature=' . $signature;

• Python

  import hmac
  import hashlib

  options = '/h/demo2/te/lo.cgi?Action=Launch&pt=AccessToken&ts=unixtimestamp';
  signature = hmac.new(str('Signature Key'), options, hashlib.sha256).hexdigest()
  url = options . '&signature=' . signature;