A greeting from Cleverthings

Hey there!
Thank you for visiting us!
If you came here is because you want to understand how token2go API works.
So, let’s do it !
This tutorial will lead you through the essential information you need to properly use this API. However, if any doubts still remains or want to suggest new features, please feel free to contact us via discussion forum or via our Slack Channel in http://cleverthingsgroup.slack.com.

Typical Use Case : Why to use Token2GO API ?

Token2GO is a cloud-based RESTful API intended to generate unique and verifiable tokens (cryptographic id codes). Use this tokens as an URL parameter in your marketing or customer service campaigns to validate requests that occurs in a timely period previously defined by your system. Don’t worry on creating cryptographic collision-free id codes in your backend application or creating usage statistics of how many times an id code was verified. Just invoke this API to create as many unique and verifiable id codes you need, and at every time you need just call this API again to validate a given id code your application received.

Example:
Suppose you intend to contact some of your customers by email or SMS as part of a promotional campaign for the sale of a certain product valid for a limited period of time and want them to engage with your website following an unique URL Link in the message, by which you can identify the user and knows exactly what the request is about.

For that purpose, you create a customer target list containing some attributes such as: customer_id, product_id, campaign_id, duration and a token.

The token is what you need to be unique (and verifiable later on) for each customer and must encode some of these attributes.

That’s is here where token2GO API comes in!

The token that will be generated will be an URL parameter you will add to the messages to be sent to your customers:

https://mystore.com/promotions/2548a499367f4c2f87fd4873a97a6ff6
https://mystore.com/promotions/8098f386792e4feeadd46d5fc1335eb7

In this case, 2548a499367f4c2f87fd4873a97a6ff6 is the token you encoded for customer 1 and 8098f386792e4feeadd46d5fc1335eb7 for customer “n”.

To encode each token, your backend application invokes token2go API passing some attributes such as: base url, customer_id, campaign_id and duration

An object containing the encoded token and the url_link is then returned back to your backend application, which can finally grab this (like in the example above) and include in the message:

“Dear customer,
During next 24 hours, MyStore will be selling all housing products with discount!
Follow this link https://mystore.com/promotions/2548a499367f4c2f87fd4873a97a6ff6 and grant your 50% OFF!”

Whenever customers follows the link performing a web request to https://mystore.com/promotions/2548a499367f4c2f87fd4873a97a6ff6, your backend application invoke again token2GO API to validate the token and also get more (encoded) information regarding the customer or whatever attributes you used in the encoding.
If the token is still valid (i.e: it is not expired or the signature was not compromised or tampered, your backend application will get a HTTP 200 response, otherwise an HTTP 40x error will be returned and a detailed message will be provided (i.e: “token expired”, “invalid signature”)