User API

The user API, which is one of the Kentik V5 Admin APIs, is covered in the following topics:

• About the User API
• User JSON
• User List
• User Info
• User Create
• User Update
• User Delete

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.

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 Manage Users), which is listed under "Security" in the sidebar of the Admin section of the Kentik portal.

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:

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

This GET method retrieves a list of a customer's Kentik 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):

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

This GET method retrieves information about a single user, identified by ID, in the list of a customer's Kentik 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):

Notes:
- 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.
- 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 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.

This POST method adds a new user to a customer's Kentik 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):

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:

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.

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):

Notes:
- 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.
- 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 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.

This DELETE method removes one user, identified by ID, from a customer's collection of Kentik 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):

Notes:
- 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.
- 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.