TWIPLA 3AS API (3.0.3)
Last updated: 2026-09-25
- 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.
The Twipla 3AS approach relies on a straightforward flow of data that can be easily integrated into any backend system.
- First thing in the integration process a public/private key must be created. The resulting public key is shared with TWIPLA
- The INTP account is created resulting in an
intpId(that can be used to create tokens) and a default set of packages - 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
- Create a new customer with a website
- Inject the resulting tracking code in the website's HTML
- Create the TWIPLA Dashboard url
- Show an iframe to the user with the url created previously
- Show a modal to the user to upgrade his subscription
- Display all the available packages using the API
- After the payment is complete, use the API to upgrade the subscription of the website
- Create an RSA Key Pair (PEM format)
- Send the resulting public key (
jwtRS256.key.pub) to the TWIPLA Dev Team - Use the resulting private key to sign an INTP JWT Token which will authenticate all API requests
- Use the resulting private key to sign an INTPC JWT Token which will authenticate the TWIPLA Dashboard IFrame request
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 Authorization header Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
JWT tokens can be easily created in most programming languages using an appropriate library from jwt.io
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
- Create the keypair:
ssh-keygen -t rsa -b 2048 -m PEM -f jwtRS256.key - Convert the public key to PEM:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
- Header
{
"alg": "RS256",
"typ": "JWT",
"kid": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
}
- 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
}
- 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").
- Header
{
"alg": "RS256",
"typ": "JWT",
"kid": "UUID" // the id issued by TWIPLA for an INTP, in exchange for `jwtRS256.key.pub`
}
- 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
}
- 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
intpcToken / intpc_token- a token for INTPC authenticationexternalWebsiteId- the website id issued by the INTP (intpWebsiteId), the target website in the IFrame DashboardupgradePackageId- 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 withplatform_managedbilling mode.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,frtimezone- 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/HonolulustartDate- sets the start of the date range filter. Format: YYYY-MM-DDendDate- sets the end of the date range filter. Format: YYYY-MM-DD