The Hosting Partner API
Hosting partners can easily integrate Tideways into their service offerings with our automation API. Partners can create and delete accounts with projects and provide a Single Sign-On into the Profiler from your hosting control panel.
Our implementation follows Heroku’s Kensa API, which is an industry standard for integration of external addons into hosting services. We have extended it slightly to improve it for different hosting providers.
A "Tideways Resource" in Kensa terminology represents a single Tideways unit for monitoring, profiling and exception tracking a project on your hosting platform. We call this "Project" in Tideways, which are grouped under an "Organization".
We define API operations for provisioning, updating and de-provisioning of Tideways projects, based on this standard. Your automation can make use of them to:
-
Automatically create Tideways resource for all your customers projects
-
Allow your customers to add Tideways resource to their hosting contract as paid addon
When a project is created through the Kensa API a set of configuration variables is returned back to you for use as environment variables.
Registering as Hosting Partner
If you are interested in the Hosting Partner API, get in contact with us at [email protected].
As a partner you will receive a HTTP Basic Username + Password, a Single Sign-On Salt and two URLs for API and Sign-On respectively.
| Keep this information secret, because it is possible to create projects with them that will get billed in your account. |
Tag Customer Accounts via Daemons with Partner Claim Token
You can run the tideways-daemon service on your hosting platform with a specially generated "Partner Claim Token". All Tideways accounts that are transmitting data through one of these daemons running in this mode will automatically open a workflow where our support team can accept or reject the account to belong to your hosting partner account. This is a simplification of the "Bring your own License" workflow, described next, because it only requires automating the daemon setup on your infrastructure to use the claim token during tideways-daemon startup.
-
Visit your Partner Administration page and open the screen "Keys".
-
If no claim key has been generated yet, generate new keys; otherwise copy the claim key.
-
Modify the startup arguments of tideways-daemon to include the "--partner-claim-key". The easiest way is to modify or create
/etc/default/tideways-daemonto include the following content:
TIDEWAYS_DAEMON_EXTRA="--partner-claim-key=yourKeyHere"If you are already using the TIDEWAYS_DAEMON_EXTRA configuration variable to modify other argument, append the flag to the end of the environment variable as a new argument.
| See the Daemon documentation for more information. |
| The partner claim key is only used to make a connection between Tideways accounts and your hosting partner account, so there is no risk if the key is readable to your customers. |
Bring Your Own License Workflow
When your customers sign up for Tideways on their own and can pass the Tideways API Key into your hosting control panel, you can use the "Bring Your Own License" workflow. This is where you use our REST API to send us the API keys of the customers, when they enter it into the control panel for the first time. This is much simpler to implement then the Kensa Workflow, where you create and maintain the Tideways accounts and projects from your hosting control panel.
You need your Kensa Username+Password for this, generated from the Partner Administration screen.
The endpoint for claiming organizations is the following URL:
POST https://app.tideways.io/api/partner/{partner}/claim-organizations
Use the Kensa Username+Password for HTTP Basic Authentication and send a payload of api_keys as form body in the following format:
api_keys[]=foo&api_keys[]=bar
Using cURL this can be done with:
curl -X POST \
-u kensa:pass \
-d api_keys[]=foo \
-d api_keys[]=bar \
https://app.tideways.io/api/partner/{partner}/claim-organizationsIn PHP, you can send this organization claim payload with the following snippet:
<?php
$partnerName = "";
$partnerKensaUser = "";
$partnerKensaPassword = "";
$url = "https://app.tideways.io/api/partner/$partnerName/claim-organizations";
$apiKeys = ["foo", "bar"];
$auth = base64_encode(sprintf(
"%s:%s", $partnerKensaUser, $partnerKensaPassword
));
$options = array(
'http' => array(
'header' => "Content-type: application/x-www-form-urlencoded\r\nAuthorization: Basic $auth\r\n",
'method' => "POST",
'content' => http_build_query(['api_keys' => $apiKeys]),
)
);
$result = file_get_contents($url, false, stream_context_create($options));
var_dump($result);Implementation Guidelines
To integrate with our Kensa API, your platform must execute code during specific events that happen during your customers lifecycle:
-
During "New Project created" or "Tideways Addon activated" events, you should execute a Provision Tideways resource request using the API credentials that we provide you with. You pass along the customers account, project name and a UUID. Tideways API returns at least two environment variables back to you containing the Tideways API Key and sample rate, potentially more. You can store this configuration information in a database for the customers project if you want to re-use it during deployment.
-
During the "Deployment" event, access the Tideways configuration information from your database and configure the PHP environment of your customer with them. If you don’t want to store the credentials in a database, then you can make a HTTP request again to the provision resource with the same UUID and get access to the environment variables again.
-
During the "Project deleted" event of the customers project, send a de-provision request to delete the Tideways resource on our end.
API
Provision a Tideways Resource
To provision a new Tideways resource, you can perform the following POST request:
POST https://app.tideways.io/api/{partner}/resources
Content-Type: application/json
Authorization: Basic [Your Username]:[Your Password]
{
"uuid": "unique id or uuid for the project in your system",
"account_name": "customer_example",
"application_name": "www.example.com",
"plan": "starter|basic|standard|pro"
}
The uuid contains an id that is unique in your system and references the project to be monitored in Tideways.
You must specify account_name and application_name or alternatively the heroku_id property which means they are both the same.
We recommend to use the account_name and application_name and if you use the same account_name for multiple projects.
When doing so, users that log into one of the project through Single Sign-On will also be able to see the others.
As a response, you will receive the following payload as JSON:
{
"id": "our id, keep it for updates and deletes",
"name": "organization/application",
"config": {
"TIDEWAYS_APIKEY": "key",
"TIDEWAYS_SAMPLERATE": "30"
},
"php.ini": {
"tideways.api_key": "key",
"tideways.sample_rate": "30"
},
"deploy_url": "url to call to trigger a release event in Tideways"
}You should then use the two config variables to modify the PHP environment of your customer automatically, so that the Profiler starts working automatically.
You can do this by installing and activating the Tideways extension on your customers server(s) and set the API-Key and Sample-Rate via php.ini using the "php.ini" key or php-fpm environment variables configuration using the "config" key in the response.
During a deployment you can use the "deploy_url" to trigger a release event.
Example Request for a fictional "megahosting" company:
POST https://app.tideways.io/api/megahosting/resources
Content-Type: application/json
Authorization: Basic megahosting114:foobar
{
"uuid": "5395820d-7d57-442f-8870-4e98ef1c6272",
"account_name": "petstore_Ltd",
"application_name": "www.petstore.com"
}
Response:
{
"id": "10980982",
"name": "megahosting-petstore_Ltd/www.petstore.com",
"config": {
"TIDEWAYS_APIKEY": "abcdefg123456",
"TIDEWAYS_SAMPLERATE": "30"
},
"php.ini": {
"tideways.api_key": "abcdefg123456",
"tideways.sample_rate": "30"
},
"deploy_url": "https://app.tideways.io/api/events/heroku/10980982/b0a8f60466014bb5bc8ef7dc1b76490403bb9577c04d343458da07b3970d8f8b"
}Update a Tideways Resource’s Plan
You can update the plan of a project by sending a PUT request:
PUT https://app.tideways.io/api/{partner}/resources/{id}
Content-Type: application/json
Authorization: Basic [Your Username]:[Your Password]
{
"uuid": "unique id or uuid for the project in your system",
"plan": "starter|basic|standard|pro"
}
You can alternatively use the heroku_id instead of uuid.
This is available for legacy reasons.
Delete a Tideways Resource
You can delete a resource by making a DELETE request to the resource:
DELETE https://app.tideways.io/api/{partner}/resources/{id}
Authorization: Basic [Your Username]:[Your Password]
Notify Tideways of Deployment or Release
The provisioning payload contains a deploy url that you can use to create release events in the Tideways UI. Using the URL and the following example payload you can get this feature working easily:
POST https://app.tideways.io/api/events/heroku/7807/abcdefg1234567890 release=version_xyz&app=name of project&user=deploying user&url=url of the deployed site
Parameters:
|
Contains the name of the release, the version number or commit hash for example. |
|
(optional) Contains the name of the user that triggered the release |
|
(optional) Contains the name of the application, used in the description of the event only |
|
(optional) Contains the url to the project, used in the description of the event only |
SSO Login
To log in users from your control panel to the Profiler, you can use the SSO API. It is implemented by sending a signed POST request through a form to the Profiler SSO endpoint:
<form method="POST" action="https://app.tideways.io/sso/login/{partner}">
<input type="hidden" name="id" value="your application uuid"/>
<input type="hidden" name="timestamp" value="unix timestamp"/>
<input type="hidden" name="token" value="authentication token"/>
<input type="hidden" name="email" value="users email"/>
</form>A sample request then looks like:
POST https://app.tideways.io/sso/login/{partner}
Content-Type: application/x-www-form-urlencoded
id=1&timestamp=1416476493&[email protected]&token=629db2f3c433d80686af95f4aad4269d
The token has to be generated on your server-side using the SSO salt that we have provided you with and the choice of algorithm:
<?php
$id = "your uuid provided in provisioning request.";
$timestamp = time();
$token = hash_hmac('sha256', $id . ':' . $timestamp, $ssoSalt);The timestamp is used to validate that the single sign-on token is not older than two hours. The email is used to create an account.
On the first login with SSO, this triggers an invitation workflow where the user has to confirm that they want to accept the invitation to this organization by you as partner. This is done for security purposes.
API to Invite Users to Organization
You can invite users to a partner organization by their e-mail address:
POST https://app.tideways.io/api/{partner}/resources/{uuid}/invitations
Content-Type: application/json
{
"emails": ["[email protected]"]
}
Users with the email address will get an invitation to the organization with your given UUID during the Provision API request. Only one invitation is sent even when the request is made multiple times, and users can confirm or deny the invitation.