API Reference
Introduction
The Automation API is a REST API that allows almost every action that is possible via our standard (web-based) user interfaces to be also triggered and performed programmatically. This means that you can write your own software / code interacting with our platform, harnessing all of its features and capabilities. As an example, some of our customers took advantage of this API to implement bridges between Kameleoon and their own Git repositories, so that Kameleoon variations code can be managed directly on their usual version control system. You could also design your own dashboard and fill it with experiment results directly obtained from Kameleoon. Building custom systems operating or interfacing with Kameleoon is easy thanks to this API.
This is the reference documentation for version 1.0 of the Automation API. Code samples are on the right section. This API is a REST compliant API, so you can call it with any REST capable framework in any language (Java, C#, NodeJS, Python, etc). We conform to REST conventions and any developer familiar with those should feel at ease here.
Some endpoints and parameters are still expected to change as we refine our Automation API and release new versions. If you wish to be notified in advance of any planned API changes, please contact your Customer Success Manager to be manually added to a mailing list.
This API is not intended to be used extensively. By this we mean it's intended to be called a dozen of times per minute and per customer / user account on our systems. It's not scalable to millions of calls per minute, so should not be called for every visitor on your website (if you need this, see the Data API instead for more information).
If you notice something is absent from our current Automation API, which would be useful for you, do not hesitate to contact our teams to ask for an improvement. We can change the Automation API quickly and welcome any feedback from our customers.
Authentication
The Automation API uses the OAuth 2.0 framework to manage authorization. It's an industry-standard protocol nowadays for web applications, so a lot of developers should already be familiar with it. The most important thing to understand with OAuth 2.0 is that this framework supports several flows (or use cases).
With respect to Kameleoon, there are two flows that are relevant for the Automation API:
- If you're a Kameleoon customer who intends to use the Automation API for your own purposes, you will need to use the Client credentials flow. This will allow you to control your Kameleoon account and associated web properties programmatically. For instance, you could build a bridge between your CMS (Content Management Software) and Kameleoon, automatically creating and running AB experiments based on the contents of your CMS platform.
- If you're a technological partner of Kameleoon, and you intend to build an integration between your own application and Kameleoon, you will need to use the Authorization code flow. This will allow you to distribute software for users of both platforms / services (Kameleoon and your own). For instance, you would use this to access AB experiments results from Kameleoon and present them in your own application.
Client Credentials Flow
The Client Credentials Flow is the simplest flow. For this flow, you only need to obtain an access token by providing a client_id and a client_secret to an authorization end-point. You will then be able to access the Automation API by using this token as a Bearer Token present in a Authorization HTTP request header.
To obtain your credentials (client_id and a client_secret), login to the Kameleoon platform. Go to your profile page (top right circle -> My profile) and click on the See my API credentials link.
Obtaining an access_token
Authorization request
curl \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
"https://api.kameleoon.com/oauth/token"
You send a POST request to the https://api.kameleoon.com/oauth/token endpoint. Your client_id and client_secret should be sent as parameters in the body.
Authorization response
{
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA"
}
The authorization server then replies with a JSON object, containing an access_token.
Using the access_token to access the API
REST API example request
curl \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"
Using the access_token, you can make standard REST web API calls. It should be supplied in the Authorization request header to prove your identity.
The general Automation API endpoint is https://api.kameleoon.com.
For the Client Credentials flow, there is no refresh tokens. An access token is valid for a duration of 2 hours by default.
All API requests must be made over HTTPs. Calls made over plain HTTP will fail. API requests without authentication will also fail.</:::
Authorization Code Flow
The Authorization Code Flow is a flow adapted to partners or third party developers that need to integrate their applications with data from the Kameleoon platform. For this flow, you need to obtain permission from one of your users to access its Kameleoon account. The process will provide you with an authorization code that you need to exchange for an access token. You will then be able to access the Automation API by using this token as a Bearer Token present in a Authorization HTTP request header.
You should first ask your contact at Kameleoon to create an OAuth application in our system for you. You will need to specify a redirect URL (on your own web application). Once the application is created, you will need to know its name, which is used as the client_id value in the flow below. You will also be provided with a client_secret.
:::
Obtaining authorization from the user
Initial request URL
https://api.kameleoon.com/oauth/authorize?client_id=my-application-name&response_type=code&redirect_uri=https://application.company.com/ HTTP/1.1
In your web application, you need to redirect your user to the following URL. He will be asked to login to the Kameleoon platform (if he's not already logged), and will be presented with an interface asking him to grant access to his Kameleoon data / resources.
Redirect URL
https://application.company.com/?code=AUTHORIZATION_CODE
Once your user has been authenticated and has granted permission to access their Kameleoon account, they will be redirected to your application URL with an authorization code as a query parameter.
Obtaining an access_token
Authorization request
curl --location --request POST 'https://api.kameleoon.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic dGVzdC1iby1hdXRob3JpemF0aW9uLWNvZGU6VzlSU3VVRmh0U01pSVNKb2VMNl9SOFhneFVKcWNWZFVuNENmdG44a0Z5WQ==' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=MagXU69dAxOb8Ry7UgXVTUdHSfdICaqXB-Ts86ay1L0' \
--data-urlencode 'redirect_uri=https://application.company.com/'
You can then exchange the authorization code for an access token and a refresh token. On the POST request, the value in the Authorization: Basic corresponds to the Base64 encoded value of the string client_id:client_secret (for instance my-application-name:x8er46f2gtZ). The code parameter contains the authorization code obtained in the previous step. Finally you need to provide your redirect_uri as well.
Authorization response
{
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA",
"refresh_token": "eyJraWQiOiJrYW1lbGVvb24tZ3Jhdml0ZWUtQU0ta2V5IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiIzMzA2MTM2MC1mMjZiLTQ2MTctODYxMy02MGYyNmIxNjE3M2QiLCJhdWQiOiJ0ZXN0LWJvLWF1dGhvcml6YXRpb24tY29kZSIsImRvbWFpbiI6ImthbWVsZW9vbiIsImlzcyI6Imh0dHA6XC9cL2FwaS5rYW1lbGVvb24uY29tXC9hbVwva2FtZWxlb29uXC9vaWRjIiwiZXhwIjoxNjIxNTMzNzE5LCJpYXQiOjE2MjE1MTkzMTksImp0aSI6IlFwWERPVmhtNDFHX1RsWDUwVUYySUZkQ1hqaDhZVnBlaW5RcjdyeEdHUUEifQ.81nlwYpaoU_Y0T-WaCcPS9kgh3nTpIVFeydhzGtJfVU"
}
The authorization server then replies with a JSON object, containing access_token and refresh_token keys.
Using the access_token to access the API
REST API example request
curl \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"
Using the access_token, you can make standard REST web API calls. It should be supplied in the Authorization request header to prove your identity.
The general Automation API endpoint is https://api.kameleoon.com.
Obtaining a refresh_token
Authorization request
curl --location --request POST 'https://api.kameleoon.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic dGVzdC1iby1hdXRob3JpemF0aW9uLWNvZGU6VzlSU3VVRmh0U01pSVNKb2VMNl9SOFhneFVKcWNWZFVuNENmdG44a0Z5WQ==' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=eyJraWQiOiJrYW1lbGVvb24tZ3Jhdml0ZWUtQU0ta2V5IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiIzMzA2MTM2MC1mMjZiLTQ2MTctODYxMy02MGYyNmIxNjE3M2QiLCJhdWQiOiJ0ZXN0LWJvLWF1dGhvcml6YXRpb24tY29kZSIsImRvbWFpbiI6ImthbWVsZW9vbiIsImlzcyI6Imh0dHA6XC9cL2FwaS5rYW1lbGVvb24uY29tXC9hbVwva2FtZWxlb29uXC9vaWRjIiwiZXhwIjoxNjIxNTMzNzE5LCJpYXQiOjE2MjE1MTkzMTksImp0aSI6IlFwWERPVmhtNDFHX1RsWDUwVUYySUZkQ1hqaDhZVnBlaW5RcjdyeEdHUUEifQ.81nlwYpaoU_Y0T-WaCcPS9kgh3nTpIVFeydhzGtJfVU'
Obtaining a refresh_token is done in the same way as obtaining an access_token. Follow the example on the right.
Rate Limiting
Rate limiting of the automation API is primarily on a per-user basis - or more accurately described, per user access token.
Rate Limiting Windows
The Automation API uses two rate limiting windows. The first one is defined over a 10 seconds interval; no more than 50 requests from the same user are accepted. The second one is defined over a 1 hour interval; no more than 1000 requests from the same user are accepted.
When an application exceeds the rate limit for a given standard API endpoint, the API will return a HTTP 429 “Too Many Requests” response code.
Tips to avoid being Rate Limited
The tips below are there to help you code defensively and reduce the possibility of being rate limited. Some application features that you may want to provide are simply impossible in light of rate limiting, especially around the freshness of results. If real-time information is an aim of your application, look into the Data API.
Caching
Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the Automation API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.
HTTP status codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Your request was correctly formatted and the resource you requested is returned |
| 201 | Created | Returned when a POST request was successful |
| 400 | BadRequest | Can happen if your request did not have a valid JSON body. It might help to specify a Content-Type: application/json header in your request. If you sent valid JSON, the error may also reference specific fields that were invalid |
| 401 | Unauthorized | Your API token was missing or not in the correct format |
| 403 | Forbidden | You provided an API token but it was invalid or revoked or you don't have read/write access to the entity you're trying to view/edit |
| 429 | Too Many Requests | You sent too many requests and were rate limited. See section about rate limiting for details |
| 5xx | Server Error | Something went wrong! Kameleoon engineers have been informed, but please don't hesitate to contact us. |