My Kentik API

The My Kentik API, which enables management of the My Kentik Portal, is covered in the following topics:

Notes:
- For an overview of all Kentik APIs, see APIs Overview.
- For information on using this API with cURL, see API Access Via cURL.
- For documentation of the V5 Query API, see V5 Query API.
- For documentation of the V5 Alerting APIs, see V5 Alerting APIs.
- To test V5 APIs, see V5 API Tester.
- For assistance using any API version please contact support@Kentik.com.

 

About My Kentik API

Note: Users whose level is Member have access only to the GET methods of Admin APIs.

The Kentik V5 Admin APIs include an API that enables programmatic management of tenant settings (see About Tenancy) for the My Kentik Portal. The API enables much — but not all — of the functionality of the My Kentik Portal page in the Kentik portal, which is listed under Customize in the Admin sidebar.

Note: To add, update, or delete a tenant, you must currently use the portal UI (see My Kentik Portal Page).

 

Tenant JSON

Calls to the My Kentik API each return an HTTP response body containing a tenant object in JSON (or, in the case of the Tenant List call, an array of such objects). The object is made up of the fields (name:value pairs) shown in the example below (placeholders in italics).

{
  "id": ###,
  "name": "tenant_name",
  "description": "Everything you might wish to know about this tenant.",
  "users": [
    {
      "id": "user_id",
      "user_email": "user@domain.suffix",
      "last_login": "2019-03-01T17:48:51.113Z",
      "tenant_id": "###",
      "company_id": "####"
    }
  ],
  "created_date": "2018-10-11T22:52:05.833Z",
  "updated_date": "2019-01-11T16:23:17.267Z"
}

The fields of each tenant object contain information on one tenant in your organization's collection of tenants. These fields are described in the tables below.

Note: For further information about the settings represented by the name:value pairs below, see About Tenant Settings.

Tenant Object

The tenant object is the top-level object returned from calls to the My Kentik API.

JSON name Type Description
id number Kentik-assigned ID of the tenant.
company_id string Kentik-assigned ID of the customer with which the tenant is associated.
name string Customer-assigned tenant name.
description string Description of the tenant.
cdate string Date-time of tenant creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
edate string Date-time tenant was most recently edited.
users array See Users Array.

Users Array

The users array is a collection of objects that each represent a user assigned to this tenant.

JSON name Type Description
id string The system assigned id of the user.
company_id string The system assigned id of the company.
user_email string The user’s email address as provided at signup (e.g. “user@domain.suffix”).
user_name string The name provided for the user by admin at signup (e.g. “janedoe”). Valid characters: alphanumeric plus underscores.- Length: min=3, max=40.
user_full_name string The user’s full name (up to 128 characters) as provided at signup (e.g. “Jane Doe”).- Valid characters: all except double quotes.- Length: max=50.
tenant_id string Kentik-assigned ID of the tenant.
last_login string Date-time of most recent tenant login.

 

Tenant List

This GET method retrieves a JSON array made up of tenant objects that each represent an individual tenant in your organization.

Notes:
- The id value in each tenant object can be used in subsequent calls to reference that tenant.
- To try this call, go to the V5 API Tester.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

URL api.kentik.com/api/v5/mykentik/tenants
Request GET /api/v5/mykentik/tenants HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A response body containing a tenants array in JSON. The array contains an element for each of your organization's tenants; each element is a tenant object containing information about one tenant.

Note: For a description of the JSON name:value pairs in a tenant object, above see Tenant JSON.

 

Tenant Info

This GET method retrieves information about a single tenant, identified by ID, in your organization's collection of tenants.

Note: To try this call, go to the V5 API Tester.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

URL api.kentik.com/api/v5/mykentik/tenant/tenant_id
Request GET /api/v5/mykentik/tenant/tenant_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

Notes:
- The "tenant_id" value at the end of the path can be found in the id value of a tenant object in the array returned from Tenant List.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON tenant object containing information about the tenant specified with tenant_id.

Note: For a description of the JSON name:value pairs in a tenant object see Tenant JSON.

 

Tenant User Create

This POST method assigns a new user, by email address, to one of your organization's tenants. An email will be sent to the provided address, at which point the new user can verify the email address and sign in to create a password and activate the new account.

Notes:
- To update the properties of a tenant user, first delete the user and then create the user again with the corrected properties.
- To try this call, go to the V5 API Tester.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

URL api.kentik.com/api/v5/mykentik/tenant/tenant_id/user
Request POST /api/v5/mykentik/tenant/tenant_id/user HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The following parameters are passed in the request body:

Parameter Type Description
user_email string Required: A valid email address for the new tenant user.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON user object containing information about the newly added user.

Note: For a description of the JSON name:value pairs in a user object see Users Array.

 

Tenant User Delete

This DELETE method removes one user, identified by ID, from the collection of users assigned to a tenant.

Note: To try this call, go to the V5 API Tester.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

URL api.kentik.com/api/v5/mykentik/tenant/tenant_id/user/user_id
Request DELETE /api/v5/user/user_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

Notes:
- The "tenant_id" value in the path can be found in the id value in a tenant object (see Tenant Info or Tenant List).
- The "user_id" value at the end of the path can be found in the id value in a user object in the Users Array in a tenant object.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code 204, indicating that the request was received and understood but that there was no need to return a response body.
© 2014- Kentik
In this article:
×