TWIPLA 3AS API (3.0.0)

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://app-3as.visitor-analytics.io/?intpcToken=value&externalWebsiteId=value

1. intpcToken / intpc_token - a token for INTPC authentication
2. externalWebsiteId - the website id issued by the INTP (intpWebsiteId), the target website in the IFrame Dashboard
3. upgradePackageId - the ID of a 3AS pricing plan. When the upgrade page is open, this parameter will enforce a redirect to the checkout page with the pricing plan selected. It only works for INTPs with platform_managed billing mode.
4. locale - sets the UI language/locale. It uses a simple two-letter ISO 639-1 language code. Format: lowercase 2-char code — e.g. en, de, fr
5. timezone - sets the user's timezone. This parameter expects an IANA timezone identifier (also known as "tz database" / "Olson" names). Format: Area/City — e.g. Europe/Berlin, America/New_York, Pacific/Honolulu
6. startDate - sets the start of the date range filter. Format: YYYY-MM-DD
7. endDate - sets the end of the date range filter. Format: YYYY-MM-DD

The TWIPLA API key system operates on a per-website basis. Each website can have multiple API keys. API keys are used to:

• Authenticate requests to the TWIPLA API
• Enable access to the TWIPLA dashboard for the associated website

Authentication via API key

The API Key can be used to create a short-lived dashboard token which can be used to login the user into the TWIPLA dashboard safely without exposing the API Key client-side.

Dashboard Access via API Key

After the website and API key have been successfully created and securely stored server-side, follow these steps to access the TWIPLA dashboard.

Step 1 — Login via API Key

Call the Login via API Key endpoint. A successful response returns a set of access tokens required to build the dashboard URL and verify the user's identity.

Step 2 — Build the Dashboard URL

Using the refreshToken from the login response, construct the dashboard URL in the following format:

https://app-3as.visitor-analytics.io?websiteToken={refreshToken}

API access via API key

The TWIPLA API can be accessed using the X-API-Key request header. Exposed endpoints only provide access to data for the connected website with read-only capabilities.

This method is safe as long as the connection uses HTTPS and the API key is stored server-side and not exposed in client-side code.

Request Header:

{ "X-Api-Key": "twpl-bFHhQukkcKA9omBqRukM" }

Relevant API Endpoints for Website Analytics:

Additional endpoints are available depending on future requirements.

Key Rotation

The API Key can be rotated using the endpoints in 3 steps:

• Create a new key with a new expiry
• Replace usage of the key with the new one
• Allow the old key to expire or delete it

An INTP can operate under two subscription models: website-based or account-based.

Use these endpoints if your company:

• Uses website-based subscriptions
• Is responsible for managing billing directly

An INTP can operate under two subscription models: website-based or account-based.

Use these endpoints if your company:

• Uses account-based subscriptions
• Is responsible for managing billing directly

Manage contributors for a website and control their level of access.

Any existing customer can be added as a contributor. If the customer doesn't exist yet, create them first before adding them as a contributor — no website is required at creation time.

Once added, the contributor can access the dashboard normally via the dashboard iframe URL, where the website ID is the ID of the website they contribute to.

If the website selector is enabled within the dashboard, the contributor will also see the website listed there, alongside any websites they own.

Each contributor is assigned one of the following roles: