CH logo® Knowledge Base
Contents Search
   

 

User API

The user API, which is one of the Kentik V5 Admin APIs, 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 assistance using any API version please contact support@Kentik.com.

 

 
 top

About the User API

The Kentik V5 Admin APIs include an API that enables programmatic management of user settings. The functionality of the API is roughly equivalent to the settings of the Users Page (see User Admin), which is listed under “Security” in the sidebar of the Admin section of the Kentik Detect portal.

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

 

 
 top

User JSON

Calls to the User API each return an HTTP response body containing a “user” object in JSON (or, in the case of the User List call, an array of such objects). The object is made up of the fields (name:value pairs) shown in the following example:

{
  "user": {
    "id": "#####",
    "username": "newuser",
    "user_full_name": "New Username",
    "user_email": "new_user@kentik.com",
    "role": "Member"
    "email_service": "true",
    "email_product": "true",
    "last_login": "2016-09-22T21:26:43.279Z",
    "created_date": "2016-09-22T21:26:43.279Z",
    "updated_date": "2016-09-22T21:26:43.279Z",
    "company_id": "####",
  }
}

The fields of each user object contain information on an individual user registered with a given Kentik customer (company). These fields are described in the following table:

JSON name Type Description
id
number The id of the user (system assigned), e.g.: 1111
Note: This field is the primary key for the table.
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.
user_email
string The user’s email address as provided at signup (e.g. “name@domain.suffix”).
role string The role of the user: Member (0) or Administrator (1).
email_service boolean Opt-in for service emails.
email_product boolean Opt-in for product emails.
last_login string Time in UTC of most recent login, e.g. 2015-01-27T00:32:34.559Z
created_date string Date-time of user creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
updated_date string Date-time of most-recent user edit, in UTC, e.g. 2015-01-27T01:39:17.186Z
company_id number The id of the customer (system assigned), e.g.: 9999

Note: For further information about the settings represented by the name:value pairs above, see User Settings.

 

 
 top

User List

This GET method retrieves a list of a customer’s Kentik Detect users. The list is a JSON array whose elements each correspond to an individual user.

Notes:
- The “id” value in the user object for each user can be used in subsequent calls to get information about, update, or delete that user.
- 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 https://api.kentik.com/api/v5/users
Request GET /api/v5/users 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

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A response body containing a user array in JSON. The array contains an element for each of the company’s users; each element is a user object containing information about one user.

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

 

 
 top

User Info

This GET method retrieves information about a single user, identified by ID, in the list of a customer’s Kentik Detect users.

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 https://api.kentik.com/api/v5/user/user_id
Request GET /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

Note: The “user_id” value at the end of the path can be found in the “id” value in the user object that makes up each element of the array returned from User List.

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 user specified with user_id.

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

 

 
 top

User Create

This POST method adds a new user to a customer’s Kentik Detect users.

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 https://api.kentik.com/api/v5/user
Request POST /api/v5/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

The following parameters are passed in the request body:

Parameter Type Description
user_name string Required: A user name (no spaces).
user_full_name string Required: A full name for this user.
user_email string Required: The user’s email address.
user_password string Required: The user’s password; must be at least seven characters.
role string Required: The user’s role: Member (0) or Administrator (1).
email_service boolean Required: Opt-in for service emails.
email_product boolean Required: Opt-in for product emails.

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 User JSON.

 

 
 top

User Update

This PUT method updates the information about an individual user, identified by ID, in the customer’s collection of existing users.

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 https://api.kentik.com/api/v5/user/user_id
Request PUT /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

Note: The “user_id” value at the end of the path can be found in the “id” value in the user object that makes up each element of the array returned from User List.

The parameters to be changed are passed into the call with a JSON user object that contains only the fields (name:value pairs) that are to be updated. The following example shows the user object that would be used to update the user’s preference for receipt of service emails:

{
  "user": {
    "email_service": true
  }
}

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 updated user.

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

 

 
 top

User Delete

This DELETE method removes one user, identified by ID, from a customer’s collection of Kentik Detect users.

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 https://api.kentik.com/api/v5/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

Note: The “user_id” value at the end of the path can be found in the “id” value in the user object that makes up each element of the array returned from User List.

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.
 

In this article: