General overview

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.

For sake of simplification in this document, “client” refers to backend applications that invokes token2GO API and “server” refers to token2GO API Server itself which receives and respond clients requests. Finally, a “requester” refers whom invokes via HTTP request an URL exposed by a client.

Headers and Authentication

Token2GO require an authentication method behind RapidAPI provider. In this case, you must provide a X-RapidAPI-Key and a X-RapidAPI-Host in the header of your http request.

{
‘X-RapidAPI-Key’: ‘’,
‘X-RapidAPI-Host’: ‘token2go.p.rapidapi.com’
}

Create a token

POST https://token2go.p.rapidapi.com/api/v1/token

A token creation consist of encoding a payload of client’s attributes and send it in the body. Those attributes refer to a meaningful data record of the requester on the client side that must be valid at request time.

There are a few parameters that are mandatory do create a token and they must be sent in the request:

rid: (str) Record Id. This must be an unique identifier of the requester.
url: (str) Base URL exposed by the client to the requester.
exp: (int) Token’s expiration time in minutes (time to live)
iss: (str) Issuer of this token. Tipically a campaign name/id or other client related information

Example 1:
POST https://token2go.p.rapidapi.com/api/v1/token
{
“rid”: “cust1234”,
“url”: “http://clever.com/mytag/”,
“exp”: 1440,
“iss”: “cpg_sale50_off”
}

Response 1

{
“token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyaWQiOiJjdXN0MTIzNCIsImV4cCI6MTY2MjkxMzgxMiwiX2lkIjoiNDg4NTFmMjZiNDM3NDk0ZmI0NjYxZGNkYjJjOGQwMDQifQ.nAdnSEVeqdnsItF8OBZ82cBHDZDysm1CWq6GLRcuxrQ”,
“link”: “48851f26b437494fb4661dcdb2c8d004”,
“url_link”: “http://clever.com/mytag/48851f26b437494fb4661dcdb2c8d004”
}

There are also optional parameters as follows:

cnt: (int) Set the maximum number of request for validation is allowed. After this limit is reached, the token will be no longer valid. If not provided or negative value will be considered no limit.
config: (list) Configure which attributes the server must return after the token creation. If omitted, the default values are [“link”, “token”]

The config item values to be considered are:

link: An unique string of 32 chars that represents a token.
token: A JWT (JSON Web Token) which encodes the exp, link and rid values with a server secret key.
created: An ISO8601 Datetime string representing the token creation datetime.
expires: An ISO8601 Datetime string representing the token expiration datetime.
minutes: An integer representing the token expiration expressed in minutes.

Example 2: instructing the server to return link, expiration time in minutes, and the issuer of the token:
POST https://token2go.p.rapidapi.com/api/v1/token
{
“rid”: “cust1234”,
“url”: “http://clever.com/mytag/”,
“exp”: 1440,
“iss”: “cpg_sale50_off”,
“config”: [“link”, “minutes”, “iss”]
}

Response 2

{
“iss”: “cpg_sale50_off”,
“minutes”: 1440,
“link”: “550a7a8b837d4bb3acb98eae86a49172”,
“url_link”: “http://clever.com/mytag/550a7a8b837d4bb3acb98eae86a49172”
}

Example 3: instructing the server to return link, expiration time in minutes, and the issuer of the token, and set the limit of request of 3:
POST https://token2go.p.rapidapi.com/api/v1/token
{
“rid”: “cust1234”,
“url”: “http://clever.com/mytag/”,
“exp”: 1440,
“iss”: “cpg_sale50_off”,
“config”: [“link”, “minutes”, “iss”],
“cnt”: 3
}

Response2

{
“iss”: “cpg_sale50_off”,
“minutes”: 1440,
“link”: “550a7a8b837d4bb3acb98eae86a49172”,
“url_link”: “http://clever.com/mytag/550a7a8b837d4bb3acb98eae86a49172”
}

NOTES

1. “url_link” is a fixed attribute that the server always return, and it consist of url + link. You can’t hide this attribute. If you want to return only this attribute, set config to a empty list (config: [] )
2. Avoid returning too many attributes if you don’t need them (less attributes = quicker responses)

Read a token

GET https://token2go.p.rapidapi.com/api/v1/token/{id}?t={id_type}

Read a token means get all token related details. An id and id_type must be provided.
It returns an object (paginated) containing an item list.
This endpoint must be used only to check token details and how many times it has been validated (counter value).

Valid id and id_type values are:

id_type=link, id=
id_type=jwt, id=
id_type=iss, id=

Example1: Getting a token by its link id

GET https://token2go.p.rapidapi.com/api/v1/token/550a7a8b837d4bb3acb98eae86a49172?t=link

{
“items”: [
{
“rid”: “cust1234”,
“url”: “http://clever.com/mytag”,
“exp”: 1662913988,
“iss”: “cpg_sale50_off”,
“config”: [
“link”,
“minutes”,
“iss”
],
“created”: “2022-09-10T17:33:08.856235”,
“expires”: “2022-09-11T17:33:08.856235”,
“minutes”: 1440,
“token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyaWQiOiJjdXN0MTIzNCIsImV4cCI6MTY2MjkxMzk4OCwiX2lkIjoiNTUwYTdhOGI4MzdkNGJiM2FjYjk4ZWFlODZhNDkxNzIifQ.WsmBVa8b6rn_q2kn57UTGxICCWUmxNxjXgCS4KQYiRU”,
“link”: “550a7a8b837d4bb3acb98eae86a49172”,
“counter”: 0
}
],
“total”: 1,
“page”: 1,
“size”: 50
}

NOTES

1. Everytime a client invoke validate a token endpoint, the counter is increased.
2. The value of counter represents the number of time this token was validated, which means, how many time requester has invoked client (according to implementation recommendation below)

Validate a token

GET https://token2go.p.rapidapi.com/api/v1/token/validate/{id}?t={id_type}

Validate a token. An id and id_type must be provided.

id_type=link, id=
id_type=jwt, id=

This is the endpoint clients must invoke whenever a requester invoke the client

Example1: Validate a token when a requester invokes the client
GET https://token2go.p.rapidapi.com/api/v1/token/validate/550a7a8b837d4bb3acb98eae86a49172?t=link

Response1

HTTP 200 OK

{
"detail": "validated",
"counter": 5,
"remaining_cnt": -1,
"remaining_minutes": 2

}

Where:

detail: (str) A fixed success message
counter: (int) The number of validated request the token has already been made
remaining_cnt: (int) The remanining requests validation the token still has before expire. If negative, there is no limit based on the number of validate requests.
remaining_minutes: (int) The remaining time in minutes the token still has before expire by time.

NOTES

1. Everytime a client invoke validate a token endpoint, the counter is increased.
2. The value of counter represents the number of time this token was validated, which means, how many time requester has invoked client (according to implementation recommendation)

Delete a token

DELETE https://token2go.p.rapidapi.com/api/v1/token/{id}

Remove a token by its link id.

Example1: Remove a token
GET https://token2go.p.rapidapi.com/api/v1/token/550a7a8b837d4bb3acb98eae86a49172

Response1

HTTP 200 OK

{
“link”: “550a7a8b837d4bb3acb98eae86a49172”,
“deleted”: 1
}

NOTES

1. “deleted” value is “0” when no record with the provided link was found or is already removed,