User API
The user API, part 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.
- The V5 API tester was discontinued in January 2025.
- For documentation of the V5 Query API, see V5 Query API.
- For documentation of the V5 Alerting APIs, see V5 Alerting APIs.
- For help with any API version, contact support@kentik.com.
About the User API
The Kentik V5 Admin APIs offer an API for managing user settings programmatically, similar to the Users Page (see Manage Users) under "Security" in the Admin section of the Kentik portal.
Note: Member-level users only have access to the GET methods of Admin APIs. |
User JSON
User API calls return an HTTP response with a JSON "user" object, or an array of such objects for the User List call. The object contains 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": "####",
}
}
Each user object contains fields with information about an individual user registered in your organization. These fields are described in the following table:
JSON name | Type | Description |
id |
number | The system-assigned user id), e.g., “1111”. Note: This field is the primary key for the table. |
user_name | string | The username provided 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 email address 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 | UTC time 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 last user edit in UTC, e.g., 2015-01-27T01:39:17.186Z. |
company_id | number | The system-assigned company id, e.g., “9999”. |
Note: For details on the settings represented by the name/value pairs, see General Settings.
User List
The User List GET method fetches a JSON array of your Kentik users, with each element representing an individual user.
Note: The "id" value in each user object can be used in subsequent calls to retrieve, update, or delete that user.
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 |
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 from the User List method includes the following elements:
- Response headers
- HTTP response code
- A response body containing a JSON array with user objects, each containing information about a user.
Note: For details on the JSON name/value pairs in a user object, see User JSON.
User Info
The User Info GET method fetches details of a single user by ID from your list of Kentik users.
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 |
Notes:
- The "user_id" value in the path corresponds to the "id" value in each user object from the User List array.
- 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 from the User Info method includes the following elements:
- Response headers
- HTTP response code
- A single JSON user object with details about the user specified by user_id.
Note: For details of the JSON name/value pairs in a user object, see User JSON.
User Create
The User Create POST method adds a new user to your organization in Kentik.
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 |
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_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 from the User Create method includes the following elements:
- Response headers
- HTTP response code
- A single JSON user object with details about the newly-added user.
Note: For details of the JSON name/value pairs in a user object, see User JSON.
User Update
The User Update PUT method modifies details of a specific user by ID in your collection of existing users.
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 |
Notes:
- The "user_id" value in the path corresponds to the "id" value in each user object from the User List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.
Parameters to be updated are included in a JSON user object with only the fields to be changed. The following example updates the user’s service email preference:
{
"user": {
"email_service": true
}
}
HTTP Response
A successful response from the User Update method includes the following elements:
- Response headers
- HTTP response code
- A single JSON user object with details about the newly-updated user.
Note: For details of the JSON name/value pairs in a user object, see User JSON.
User Delete
The User Delete method removes a specific user by ID from your collection of Kentik users.
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 |
Notes:
- The "user_id" value in the path corresponds to the "id" value in each user object from the User List array.
- 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 from the User Delete method includes the following elements:
- Response headers
HTTP response code 204 (no content)