Terms

• INTP (Integration Partner) The company that is integrating the analytics as a service solution (3AS)
• STPs (Server Touchpoints) Credits used to measure data usage for a given website
• Customer (INTPC integration partner customer) One user of the INTP, can have many websites
• Website The website where data will be tracked. It has a subscription with a package with a certain limit of STPs. This subscription can be upgraded or downgraded. When the website is created a tracking code snippet is returned that must be embedded within the websites HTML.
• Package A package has a price and contains a certain number of STPs. They are used when upgrading/downgrading the subscription of a website.

General

The Twipla 3AS approach relies on a straightforward flow of data that can be easily integrated into any backend system.

1. First thing in the integration process a public/private key must be created. The resulting public key is shared with TWIPLA
2. The INTP account is created resulting in an intpId (that can be used to create tokens) and a default set of packages
3. The INTP is then free to create customers and websites with any package

Most endpoints that deal with customers or websites support an external ID which can be provided and then used for all following requests.

For example creating a new customer with a website requires an intpCustomerId and an intpWebsiteId. These must be provided by the INTP and are intended to make integrations easier because there is no need to save any external IDs. Then when getting data about a customer the request is done using the same intpCustomerId provided on creation.

Example implementation flow

1. Create a new customer with a website
2. Inject the resulting tracking code in the website's HTML
3. Create the TWIPLA Dashboard url
4. Show an iframe to the user with the url created previously
5. Show a modal to the user to upgrade his subscription
6. Display all the available packages using the API
7. After the payment is complete, use the API to upgrade the subscription of the website

1. Create an RSA Key Pair (PEM format)
2. Send the resulting public key (jwtRS256.key.pub) to the TWIPLA Dev Team
3. Use the resulting private key to sign an INTP JWT Token which will authenticate all API requests
4. Use the resulting private key to sign an INTPC JWT Token which will authenticate the TWIPLA Dashboard IFrame request

Overview

All authentication is done based on JWT Tokens. These are created and signed by the INTP and validated by the TWIPLA API for each request using the public key provided in the on-boarding.

The token must be sent with every request as a Bearer token in the Authentication header Example:

Authentication: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c 

JWT tokens can be easily created in most programming languages using an appropriate library from jwt.io

INTP and INTPC Tokens

INTP Token: Integration partner token used for endpoints that deal with modifying customers or websites
INTPC Token: Integration partner customer token used to give access to the dashboard and data of a particular customer

Signing JWTs

Creating an RSA Key pair

1. Create the keypair: ssh-keygen -t rsa -b 2048 -m PEM -f jwtRS256.key
2. Convert the public key to PEM: openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Structure of an INTP 3AS JSON Web Token

1. Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
}

2. Payload

{
  "roles": [
    "intp"
  ],
  "intp_id": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
  "exp": 1667215913, // expires at
  "iat": 1667215313 // issued at
}

3. Signature

To create the signature, you have to use the encoded header, the encoded payload, the generated private key and the algorithm specified in the header (e.g., "RS256").

Structure of an INTPC 3AS JSON Web Token

1. Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
}

2. Payload

{
  "roles": [
    "intpc"
  ],
  "intp_id": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
  "intpc_id": "string" // the id issued by the INTP for a customer (INTPC)
  "exp": 1667215913,
  "iat": 1667215313
}

3. Signature

To create the signature, you have to use the encoded header, the encoded payload, the generated private key and the algorithm specified in the header (e.g., "RS256").

https://stage-dashboard-3as.va-endpoint.com?intpc_token=intpc_jwt_token&externalWebsiteId=intpWebsiteId

1. intpc_jwt_token
2. intpWebsiteId - the website id issued by the INTP, the target website in the IFrame Dashboard