The Hosting Partner API

Hosting partners can 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.

A "Tideways Resource" in represents a single Tideways project unit for monitoring, profiling and exception tracking a project on your hosting platform. These "Project" in Tideways are grouped under an "Organization", which holds "User" and their access to all projects.

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 a Tideways resource for a customer

  • Allow your customer to add Tideways resource to their hosting contract as paid addon

When a project resource is provisioned through the Hosting Partner API, configuration variables are returned back to finalize the setup on your end. This includes API Keys, php.ini configuration suggestions and a deployment trigger endpoint.

Registering as Hosting Partner

If you are interested in becoming a hosting partner, see our partner page with details and get in contact with us at [email protected].

If you have a partner account, you can generate your personalized HTTP Basic Username + Password, a Single Sign-On Salt and two URLs for API and Sign-On respectively from the "Partner Administration".

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.

  1. Visit your Partner Administration page and open the screen "Keys".

  2. If no claim key has been generated yet, generate new keys; otherwise copy the claim key.

  3. Modify the startup arguments of tideways-daemon to include the "--partner-claim-key". The easiest way is to modify or create /etc/default/tideways-daemon to 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 API

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 Claim 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 easier to implement then the Provisioning API Workflow, where you create and maintain the Tideways accounts and projects from your hosting control panel.

You need your Hosting Partner API Username+Password for this, generated from the Partner Administration screen.

Claim Organizations by API Key

The endpoint for claiming organizations is the following URL:

POST https://app.tideways.io/api/partner/{partner}/claim-organizations

Use the 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 user:pass \
  -d api_keys[]=foo \
  -d api_keys[]=bar \
  https://app.tideways.io/api/partner/{partner}/claim-organizations

In PHP, you can send this organization claim payload with the following snippet:

<?php

$partnerName = "";
$partnerUser = "";
$partnerPassword = "";

$url = "https://app.tideways.io/api/partner/$partnerName/claim-organizations";
$apiKeys = ["foo", "bar"];
$auth = base64_encode(sprintf(
    "%s:%s", $partnerUser, $partnerPassword
));

$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);

Provisioning API

Implementation Guidelines

To integrate with our Hosting Partner 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.

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",
    "project_size": 1,
    "webhook_url": "https://example.com/hook"
}

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 (example customer name) and application_name (ex domain of project) property. Reuse the account_name if you want to register multiple projects for one customer.

As a response, you will receive the following payload as JSON:

{
  "id": "our id, keep it for updates and deletes",
  "uuid": "your uuid",
  "name": "organization/application",
  "config": {
    "TIDEWAYS_APIKEY": "tw-key",
    "TIDEWAYS_SAMPLERATE": "20"
  },
  "php.ini": {
    "tideways.api_key": "tw-key",
    "tideways.sample_rate": "20"
  },
  "deploy_url": "https://app.tideways.io/api/events/external/...?service=_all&environment=production"
}

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. See the Releases Configuration page for details on the endpoints parameters.

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]

{
    "project_size": 2
}

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]

Get a Tideways Resource

Get the current state of a resource based on its Tideways internal ID returned from the provisioning endpoint.

GET https://app.tideways.io/api/{partner}/resources/{id}
Authorization: Basic [Your Username]:[Your Password]

{
    "id": 26,
    "name": "megahosting/petstore_Ltd",
    "config": {
        "TIDEWAYS_APIKEY": "tw_AGuC...",
        "TIDEWAYS_SAMPLERATE": "20"
    },
    "php.ini": {
        "tideways.api_key": "tw_AGuC...",
        "tideways.sample_rate": "20"
    },
    "deploy_url": "https://app.tideways.io/api/events/external/26/7b1...",
    "message": null
}

Get all Tideways Resources

Endpoint returns a paginated list of resources (projects) for your Hosting Partner account.

GET https://app.tideways.io/api/{partner}/resources
Authorization: Basic [Your Username]:[Your Password]

{
    "projects": [
        {
            "id": 26,
            "name": "megahosting/Petstore_Ltd",
            "config": {
                "TIDEWAYS_APIKEY": "tw_AGuC...",
                "TIDEWAYS_SAMPLERATE": "20"
            },
            "php.ini": {
                "tideways.api_key": "tw_AGuC...",
                "tideways.sample_rate": "20"
            },
            "deploy_url": "https://app.tideways.io/api/events/external/26/7b1...",
            "message": null
        }
    ],
    "pagination": {
        "page": 1,
        "total_pages": 2
    },
    "links": {
        "next": "https://app.tideways.io/api/megahosting/resources?page=2"
    }
}

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.

Still need help? Email [email protected]