Developer Integration Guide

Getting Started

Token of Trust has 3 Identity Widgets: the Verified Indicator, the Reputation Summary and the Account Connector. They can be added to an existing website by cutting and pasting the HTML snippets below.

Frontend Setup

Before you place widgets in your pages you'll need to include the embed Javascript on each page.

Placing ToT Widgets

After you've completed Frontend Setup you can copy and paste the code snippets below to enable widgets where you want them rendered.

Account Connector Backend Setup

In order to protect your user's data you must acquire a secure access token. The resulting token will be used for the Account Connector widget.

Frontend Setup

Step 1

This code should appear once on every HTML page that contains a Token of Trust identity widget (even if there are multiple components on the same page). Place it right before the closing <head> tag.


<script>
(function(d){var b=window,a=document;b.tot=b.tot||function(){(b.tot.q=b.tot.q||[]).push(
arguments)};var c=a.getElementsByTagName("script")[0];a.getElementById("tot-embed")||(a=a.
createElement("script"),a.id="tot-embed",a.async=1,a.src=d,c.parentNode.insertBefore(a,c))
})("https://app.tokenoftrust.com/embed/embed.js");

tot('setPublicKey', "public_API_KEY");
</script>

Step 2

Be sure to replace public_API_KEY above with your application's public API key. If you don't have an API key yet request one now.

Placing ToT Widgets

Widgets are placed on the page using HTML <div> tags with data- attributes. The embed Javascript will automatically replace these with the matching widget.

Verified Indicator

Displays an icon if the specified user has been verified with Token of Trust.

Reputation Summary

Displays a brief summary of a user's Token of Trust reputation report and the ability to click on it to get more detail.

Account Connector

Allows your users to connect their userid from your site to their Token of Trust account.

data- attributes used for the widgets.

Data Attributes Description
data-tot-widget The widget type to build within the html element. The options as discussed further below are "reputationSummary", "accountConnector" and "verifiedIndicator"
data-tot-access-token Before rendering the "accountConnector" you must create an 'ACCESS_TOKEN' through a call to /api/connection on the server and pass the resulting value to the widget here.
data-app-userid Pass your community's unique identifier for this user. The same identifier should be used for this user when you create an 'ACCESS_TOKEN' through a call to /api/connection for Account Connector.

Verified Indicator

Verified Indicator widget displays if the user has signed up for the verification process. To avoid misleading users this should only be an indicator in lists and not used as the only indicator in a details display.

Note: If the user's account is NOT verified or connected this html element will be hidden.

Step 1

Follow the Front End Setup for the HTML page where you want to add this widget.

Step 2

Paste the following code where you want the widget to appear on the page and populate the variables. See the widget data attributes section for additional details.


<div data-tot-widget="verifiedIndicator" data-app-userid="APP_USER_ID"></div>

Reputation Summary

Reputation Summary widget displays your user's verification details, it is usually displayed on their public profile.

Note: During test the top of each widget will display a yellow 'test' banner.

Step 1

Follow the Front End Setup for the HTML page where you want to add this widget.

Step 2

Paste the following code where you want the widget to appear on the page and populate the variables. See the widget data attributes section for additional details.

<div data-tot-widget="reputationSummary" data-app-userid="APP_USER_ID"> </div>

Account Connector

Account Connector widget allows users to connect to their profile to Token of Trust, it is usually displayed on their account management screen. Usually this page is titled "My Account," "Edit Profile" or something similar.

Note: the 'Reputation Report' buttons above just link to /app/profile - which will be your profile if you're logged in. Important: The page these are used on MUST be private to the authenticated user to prevent illicit bindings.

Step 1

Follow the Front End Setup for the HTML page where you want to add this widget.

Step 2

From your web server, create an 'ACCESS_TOKEN' through a call to /api/connection via a RESTful request to the Token Of Trust backend. This ACCESS_TOKEN will be used in the next step.

Step 3

Paste the following code where you want the widget to appear on the page and populate the variables. See the widget data attributes section for additional details.

<div data-tot-widget="accountConnector" data-tot-access-token="ACCESS_TOKEN"></div>

Other Topics

Creating an Access Token

In order to ensure that Account Connector is secure you need to establish a connection for your users. This is done by making a RESTful request from your authorized server to /api/connection which will return an access token. The access token is then injected into your html page for each user connection. Be sure to include the user's access token only in pages authenticated for the intended user.

Why do we need an access token? By creating an ACCESS_TOKEN you are authorizing this user to connect their userid from your community to their Token of Trust account. This allows them to opt into Token of Trust verification in a secure way by clicking 'Get Verified' in the Account Connector widget. The token will expire so you should generate a new token for each request.

Why can't I just do this from the browser? If you're prototyping and using test keys you CAN! If you do - please follow the approach in our Quickstart Guide. It is safe and warns you to make changes when you're ready to move to production.

Why can't I just do this from the browser - in production? Creating an access token requires your secret key and if you were to include this on the browser side you'd be giving away your secret key. This would effectively allow anyone visiting your site to use your API keys. We recieve alerts when this happens and if it does (with live keys) we reserve the right to shut down your API keys to protect your community and ours.

Can you show me a full working example of how this works? Sure! We have some node.js sample code here.

Below we show how an example 'curl' request would be built. Please consult your language or framework for the best way to make a RESTful POST request in your development environment.


curl -X "POST" "https://sandbox.tokenoftrust.com/api/connection" \
	-H "Content-Type: application/json; charset=utf-8" \
	-d "{\
	        \"totApiKey\":\"public_API_KEY\", \
	        \"totSecretKey\":\"secret_KEY\",\
	        \"appUserid\":\"APP_USER_ID\",\
	        \"appDomain\":\"YOUR LICENSED LIVE SITE\",\
# Optional: \"appCallbackUrl\":\"APP_CALLBACK_URL\",\
            \"appData\": {\
                \"givenName\":\"USERS_NAME\",\
                \"familyName\":\"USERS_NAME\",\
                \"email\":\"USERS_EMAIL_ADDRESS\",\
                \"custom\":\"STRING UP to 1024 characters\",\
                \"location\": { \"locality\" : \"Minneapolis\", \"region\": \"MN\", \"countryCode\" : \"US\" } \
            } \
	    }"

    
Data Attributes Description
totApiKey The public api key supplied to you when you were given access to Token of Trust. This key begins with 'public_'.
totSecretKey The secret api key supplied to you when you were given access to Token of Trust. This key begins with 'secret_'.
appDomain The domain(s) you registered as being the origin of your api requests - set when creating your api keys.
appCallbackUrl (Optional) - This is the path to redirect the user to once verification is complete. This should include your domain and for live keys the url must start with 'https://'.

Example: https://example.com/my-account.
appUserid Your community's unique USER_ID for the user you're making the request for - e.g. the USER_ID of the user you want to connect.
appData.givenName The first name of appUserid - if this is not consistent with information they provide Token of Trust they will indicate 'Not Verified' on your site.
appData.familyName The last name of appUserid - if this is not consistent with information they provide Token of Trust they will indicate 'Not Verified' on your site.
appData.fullName This is an optional alternative to givenName or familyName. Token of Trust makes a guess as to what the family and given name are and returns those in the connection response.
appData.email The email address of appUserid - the email address for this user on your site. This value is used as a default email for reminders to users. Note that the user may opt to change this so it should be considered a recommended value.
appData.location The user's city, state, country - in that form (country is optional). If this is not near the location they provided Token of Trust the user will indicate 'Not Verified' on your site. The best way to pass this information is in structured format so that Token of Trust doesn't have to guess - in order from most specific to least - these are: locality (city), region (state) and countryCode (2 letter ISO country Code). If you don't have location in this form you may pass a string value for the location and Token of Trust will make best effort to parse the location for you. Note: Token of Trust will return the resolved/parsed location in the response to setConnection including the structured fields above as well as an approximate longitude and latitude.

The response body will be json of the form:

{
    "content" {
        "accessToken":"ACCESS_TOKEN",
        "expires":"EXPIRATION_TIMESTAMP"
    },
    "metadata" {
        "version":"1.0.0",
        "status":200
    }
}

The structure of the object returned will always have 'content' and 'metadata' elements. The attributes of particular note are described below:

Response Attributes Description
accessToken The ACCESS_TOKEN will be a long opaque string that includes the information the server will need to complete the request to connect the user per the Account Connector section.
version The version of the accessToken.
expires Unix epoc time when the token will expire.

Trigger Start from Code

Sometimes it makes sense to trigger the start of Token of Trust verification from your code. For example, suppose you want the user to fill in a form before getting verified but you want the form submit button to trigger the start of user verification. Here's how you do it:


        tot('modalOpen', 'accountConnector', {
                accessToken: 'ACCESS_TOKEN'
        });

Note that you still need your ACCESS_TOKEN from /api/connection.

AJAX Support

If the HTML is dynamically loaded via AJAX or in a single page app (e.g. you're using AngularJS or another framework) you'll need to let Token of Trust know when a new widget is available on the page. Here's how you do that:

       tot('embedsInitialize');

Note you need to populate all the required parameters into each widget before you call 'embedsInitialize'.

Handling App Callback

After end user verification Token of Trust will pass control back to your app by invoking the appCallbackUrl. If you're a subscriber to the Reputation API - you may now invoke the API to see what the end user's verification reveals.

Token of Trust also offers you a hint of how the user's verification went by adding a 'result' query parameter to your appCallbackUrl. Here are the possible values and what they mean:

'result' values Description
noLogin The end user cancelled out of the process before log-in or failed to log-in successfully to their chosen first network (e.g. facebook).
incomplete The end user did not complete verification.
noAuthorize The end user did not to authorize Token of Trust to share their reputation report.
internalError There was a problem when trying to build or save the end user's reputation report.
success or {blank} The user successfully logged in and established a reputation report. Note that 'success' is implied when 'result' is not included or is blank.

Example Advanced Integration

Here is a more or less complete example of what a backend endpoint has to do to render a page with an access token. This is node.js but if you can build a RESTful request in your chosen framework we think this will be easily translated to any language or framework.

In this example the page with the accountConnector is rendered AFTER aquiring the accessToken and injecting it into the page. If you're writing a single page app where the user can change you may need to create an endpoint for an AJAX request that returns just the access token and then tell Token of Trust the page has changed via javascript which we talk about here.

Here are a couplet things to look for below:
  • 'appDomain' is the domain your keys are registered for.
  • Fill in 'totApiKey' and 'totSecretKey' haven't been automatically replaced below - notice we switch them and the Token of Trust endpoint depending upon whether you're testing or live.
  • Lastly, you'd dynamically supply the 'appUserid' and the 'user' object shown below.


    var test = true;
    var appDomain = 'YOUR TEST DOMAIN';
    var totApiKey = test ? 'secret_test_API_KEY' : 'secret_live_API_KEY';
    var totSecretKey = test ? 'secret_test_API_KEY' : 'secret_live_API_KEY';
    var appUserid = 'APP_USER_ID';
    var endpoint = test ? "https://sandbox.tokenoftrust.com" : "https://app.tokenoftrust.com";

    var user = {
        givenName : 'Joe',
        familyName : 'Smith',
        email : 'joe.smith@smith.com',
        custom : 'my custom string field',
        location : {
            'countryCode' : 'US',
            'locality' : 'Minneapolis',
            'region': 'Minnesota',
            'postalCode' : '55414'
        }
    };
    var body = {
        totApiKey: totApiKey,
        totSecretKey: totSecretKey,
        appDomain: appDomain,
        appUserid: appUserid,
        appData: user
    };
    var bodyAsString = JSON.stringify(body);
    request(
        {
            url: endpoint + '/api/connection/' + appUserid,
            method: 'POST',
            body: bodyAsString,
            headers: {
                'Content-Type': 'application/json'
            }
        }, function (err, response) {
            var accessToken;

            // This is where you take over - this assumes rendering a template in express.
            if (!err && response.isGood()) {
               accessToken = JSON.parse(response.body).content.accessToken;
            }
            res.render('myLoginPage',
                {
                    'totApiKey': '',
                    'totAccessToken': accessToken,
                    'endpoint' : endpoint,
                    'user': user
                });
        });

    

FAQ

Can I provide a background color for the widgets?

Answer: Yes! In fact this is the recommended approach if you have a dark background. You would do this by applying stying to the enclosing div like this... of course we recommend adding your own class to the div instead assuming you use CSS.

<div style="background:white" data-tot-widget="accountConnector" data-tot-access-token="ACCESS_TOKEN"></div>