---
title: "User APIs"
slug: "user-apis"
description: "Learn how to use Kentik's User APIs for secure user management, permissions, and data filtering with REST and gRPC methods. Start optimizing today!"
updated: 2025-08-15T19:28:03Z
published: 2025-08-15T19:28:03Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.kentik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User APIs

This article covers how to get started with the User APIs.

> [!NOTE]
> **Notes:**
> 
> - The [**API Tester**](https://portal.kentik.com/v4/core/api-tester) in the v4 Portal enables you to securely call the methods of these APIs using your organization's Kentik data.
> - For information about users in Kentik, start with [**About Users**](/v1/docs/users#about-users).
> - Protobuf and OpenAPI specifications for Kentik’s v6 APIs are available in our [**api-schema-public**](https://github.com/kentik/api-schema-public) repository.

## User Usage

The topics below provide important background information for the use of these APIs.

### Overview

The User Management API enables programmatic administration of users within your organization. The API may be used to grant permissions to users at two levels:

- **User role**: Permissions based on the level assigned to the Kentik user, either Member, Administrator, or Super Administrator (see [**About Users**](/v1/docs/users#about-users)).
- **User permissions**: Permissions granting access to specific capabilities of the Kentik platform (see [**User Permissions**](/v1/docs/users#user-roles-permissions)).

Both REST endpoint and gRPC RPCs are provided.

> [!NOTE]
> **Note:** The legacy REST-only [**User API**](/v1/docs/user-api) provides a subset of the functionality of this API.

### User Permission Identifiers

Individual user permissions are represented in this API by string-based identifiers. The table below shows the identifier used in the API for each permission that can be enabled/disabled with the checkboxes on the Permissions tab of the Edit User dialog in the Kentik portal's Users module (Settings » **Users**).

| Portal setting | API identifier |
| --- | --- |
| Cancel Queries in Forensic Viewer | forensic_viewer.cancel_queries |
| Synthetics Permissions: Create tests | synthetics.tests.create |
| Synthetics Permissions: Edit tests | synthetics.tests.edit |
| Synthetics Permissions: Delete tests | synthetics.tests.delete |
| Synthetics Permissions: Create agents | synthetics.agents.create |
| Synthetics Permissions: Edit agents | synthetics.agents.edit |
| Synthetics Permissions: Delete agents | synthetics.agents.delete |
| Connectivity Costs Permissions: View Costs | connectivity_costs.read |
| Connectivity Costs Permissions: Configure Costs | connectivity_costs.edit |

> [!NOTE]
> **Note:** The API returns an error if the same permission is both granted and denied in the same request.

#### Default Permissions

The permissions above that are enabled/disabled by default depend on the role (level) of the user:

- **Member**: All permissions in the table above are denied by default.
- **Administrator** or **Super Administrator**: All permissions are granted.

### User Filter Attribute

User filters enable Administrators to apply filters that restrict the data that can be returned from queries by a given user (see [**User Filters**](/v1/docs/users#user-filters)). In the Kentik portal these filters are set on the Filters tab of the Edit User dialog in the Users module. In this API the filters are set in the `user` object with the `filter` attribute, whose type is string. The value of the attribute is given in JSON notation. The recommended way to construct the JSON string is to configure the desired filter for one user in the Kentik portal and then copy the value of the `user.filter` attribute returned for that user by the `GetUser` RPC.

## User RPCs

The tables below provide a quick reference to key information about each Remote Procedure Call in these APIs. Use the links in the tables to see schemas for the request and/or response body (if any).

> [!NOTE]
> **Note:**To test methods using your own Kentik data, use the portal's [**API Tester**](https://portal.kentik.com/v4/core/api-tester).

### ListUsers

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| GET | /user/v202211 /users | Returns a list of all user accounts in the company. |
| \| **Request body:** None **Parameters**: None \| **Response body:** [v202211ListUsersResponse](/v1/docs/user-apis#listusersresponse) \| \| --- \| --- \| |
| **Request body:** None **Parameters**: None | **Response body:** [v202211ListUsersResponse](/v1/docs/user-apis#listusersresponse) |

### CreateUser

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| POST | /user/v202211 /users | Creates new user account based on attributes in the request. Returns attributes of the newly created account. |
| \| **Request body:** [v202211CreateUserRequest](/v1/docs/user-apis#createuserrequest) **Parameters**: None \| **Response body:** [v202211CreateUserResponse](/v1/docs/user-apis#createuserresponse) \| \| --- \| --- \| |
| **Request body:** [v202211CreateUserRequest](/v1/docs/user-apis#createuserrequest) **Parameters**: None | **Response body:** [v202211CreateUserResponse](/v1/docs/user-apis#createuserresponse) |

### GetUser

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| GET | /user/v202211 /users/{id} | Returns attributes of a user account specified by ID. |
| \| **Request body:** None \| **Response body:** [v202211GetUserResponse](/v1/docs/user-apis#getuserresponse) \| \| --- \| --- \| **Parameters**: \| Name \| Description \| Required \| Type \| \| --- \| --- \| --- \| --- \| \| id \| ID of the requested user \| true \| string \| |
| **Request body:** None | **Response body:** [v202211GetUserResponse](/v1/docs/user-apis#getuserresponse) |
| Name | Description | Required | Type |
| id | ID of the requested user | true | string |

### DeleteUser

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| DELETE | /user/v202211 /users/{id} | Deletes user account specified by ID. |
| \| **Request body**: None \| **Response body**: [v202211DeleteUserResponse](/v1/docs/user-apis#deleteuserresponse) \| \| --- \| --- \| **Parameters**: \| Name \| Description \| Required \| Type \| \| --- \| --- \| --- \| --- \| \| id \| ID of the the user account to be deleted \| true \| string \| |
| **Request body**: None | **Response body**: [v202211DeleteUserResponse](/v1/docs/user-apis#deleteuserresponse) |
| Name | Description | Required | Type |
| id | ID of the the user account to be deleted | true | string |

### UpdateUser

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| PUT | /user/v202211 /users/{id} | Replaces all attributes of a user account specified by ID with attributes in the request. Returns updated attributes. |
| \| **Request body**: [v202211UpdateUserRequest](/v1/docs/user-apis#updateuserrequest) \| **Response body**: [v202211UpdateUserResponse](/v1/docs/user-apis#updateuserresponse) \| \| --- \| --- \| **Parameters**: \| Name \| Description \| Required \| Type \| \| --- \| --- \| --- \| --- \| \| id \| System generated unique identifier \| true \| string \| |
| **Request body**: [v202211UpdateUserRequest](/v1/docs/user-apis#updateuserrequest) | **Response body**: [v202211UpdateUserResponse](/v1/docs/user-apis#updateuserresponse) |
| Name | Description | Required | Type |
| id | System generated unique identifier | true | string |

### ResetActiveSessions

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| PUT | /user/v202211 /users/{id}/reset_active_sessions | Resets active sessions for a user specified by ID. |
| \| **Request body**: None \| **Response body**: [v202211ResetActiveSessionsResponse](/v1/docs/user-apis#resetactivesessionsresponse) \| \| --- \| --- \| **Parameters**: \| Name \| Description \| Required \| Type \| \| --- \| --- \| --- \| --- \| \| id \| ID of the the user whose sessions should be reset \| true \| string \| |
| **Request body**: None | **Response body**: [v202211ResetActiveSessionsResponse](/v1/docs/user-apis#resetactivesessionsresponse) |
| Name | Description | Required | Type |
| id | ID of the the user whose sessions should be reset | true | string |

### ResetApiToken

**API: UserService**

| REST Method | REST Endpoint | Description |
| --- | --- | --- |
| PUT | /user/v202211 /users/{id}/reset_api_token | Resets API token for a user specified by ID. |
| \| **Request body**: None \| **Response body**: [v202211ResetApiTokenResponse](/v1/docs/user-apis#resetapitokenresponse) \| \| --- \| --- \| **Parameters**: \| Name \| Description \| Required \| Type \| \| --- \| --- \| --- \| --- \| \| id \| ID of the the user whose API token should be reset \| true \| string \| |
| **Request body**: None | **Response body**: [v202211ResetApiTokenResponse](/v1/docs/user-apis#resetapitokenresponse) |
| Name | Description | Required | Type |
| id | ID of the the user whose API token should be reset | true | string |

## User Schemas

This API uses the following schemas.

#### protobufAny

| **Schema:** protobufAny | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| typeUrl \| type: string \| \| value \| type: string format: byte \| |
| Name | Value |
| typeUrl | type: string |
| value | type: string format: byte |

#### rpcStatus

| **Schema:** rpcStatus | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| code \| type: integer format: int32 \| \| message \| type: string \| \| details \| type: array items: $ref: [protobufAny](/v1/docs/user-apis#protobufany) \| |
| Name | Value |
| code | type: integer format: int32 |
| message | type: string |
| details | type: array items: $ref: [protobufAny](/v1/docs/user-apis#protobufany) |

#### CreateUserRequest

| **Schema:** v202211CreateUserRequest | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| user \| $ref: [v202211User](/v1/docs/user-apis#user) \| |
| Name | Value |
| user | $ref: [v202211User](/v1/docs/user-apis#user) |

#### CreateUserResponse

| **Schema:** v202211CreateUserResponse | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| user \| $ref: [v202211User](/v1/docs/user-apis#user) \| |
| Name | Value |
| user | $ref: [v202211User](/v1/docs/user-apis#user) |

#### DeleteUserResponse

| **Schema:** v202211DeleteUserResponse | **Type:** object |
| --- | --- |
| **Properties**: None. |

#### GetUserResponse

| **Schema:** v202211GetUserResponse | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| user \| $ref: [v202211User](/v1/docs/user-apis#user) \| |
| Name | Value |
| user | $ref: [v202211User](/v1/docs/user-apis#user) |

#### ListUsersResponse

| **Schema:** v202211ListUsersResponse | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| users \| type: array items: $ref: [v202211User](/v1/docs/user-apis#user) description: Last of users in the account readOnly: true \| \| invalidCount \| type: integer format: int64 description: Number of invalid entries encountered while collecting data \| |
| Name | Value |
| users | type: array items: $ref: [v202211User](/v1/docs/user-apis#user) description: Last of users in the account readOnly: true |
| invalidCount | type: integer format: int64 description: Number of invalid entries encountered while collecting data |

#### PermissionEntry

| **Schema:** v202211PermissionEntry | **Type:** object |
| --- | --- |
| **Properties (* = required)** \| Name \| Value \| \| --- \| --- \| \| capability * \| type: string description: String identifying capability that is granted of denied \| \| allowed * \| type: boolean description: Flag indicating whether operation is allowed \| |
| Name | Value |
| capability * | type: string description: String identifying capability that is granted of denied |
| allowed * | type: boolean description: Flag indicating whether operation is allowed |

#### ResetActiveSessionsResponse

| **Schema:** v202211ResetActiveSessionsResponse | **Type:** object |
| --- | --- |
| **Properties**: None. |

#### ResetApiTokenResponse

| **Schema:** v202211ResetApiTokenResponse | **Type:** object |
| --- | --- |
| **Properties**: None. |

#### Role

| **Schema:** v202211Role | **Type:** string |
| --- | --- |
| **Attributes**: \| Key \| Value \| \| --- \| --- \| \| enum \| ROLE_UNSPECIFIED, ROLE_MEMBER, ROLE_ADMINISTRATOR, ROLE_SUPER_ADMINISTRATOR \| \| default \| ROLE_UNSPECIFIED \| \| description \| • ROLE_UNSPECIFIED: Invalid value. • ROLE_MEMBER: Member • ROLE_ADMINISTRATOR: Administrator • ROLE_SUPER_ADMINISTRATOR: Super-administrator \| |
| Key | Value |
| enum | ROLE_UNSPECIFIED, ROLE_MEMBER, ROLE_ADMINISTRATOR, ROLE_SUPER_ADMINISTRATOR |
| default | ROLE_UNSPECIFIED |
| description | • ROLE_UNSPECIFIED: Invalid value. • ROLE_MEMBER: Member • ROLE_ADMINISTRATOR: Administrator • ROLE_SUPER_ADMINISTRATOR: Super-administrator |

#### UpdateUserRequest

| **Schema:** v202211UpdateUserRequest | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| user \| $ref: [v202211User](/v1/docs/user-apis#user) \| |
| Name | Value |
| user | $ref: [v202211User](/v1/docs/user-apis#user) |

#### UpdateUserResponse

| **Schema:** v202211UpdateUserResponse | **Type:** object |
| --- | --- |
| **Properties**: \| Name \| Value \| \| --- \| --- \| \| user \| $ref: [v202211User](/v1/docs/user-apis#user) \| |
| Name | Value |
| user | $ref: [v202211User](/v1/docs/user-apis#user) |

#### User

| **Schema:** v202211User | **Type:** object |
| --- | --- |
| **Properties (* = required)** \| Name \| Value \| \| --- \| --- \| \| id \| type: string description: System generated unique identifier readOnly: true \| \| userEmail * \| type: string description: User e-mail address (serves also as username) \| \| userFullName * \| type: string description: Full name \| \| role \| $ref: [v202211Role](/v1/docs/user-apis#role) \| \| permissions \| type: array items: $ref: [v202211PermissionEntry](/v1/docs/user-apis#permissionentry) description: Optional list of permissions granted to the user \| \| filter \| type: string description: Optional JSON string defining filter for objects visible to the user \| \| lastLogin \| type: string format: date-time description: UTC Timestamp of user's last login session readOnly: true \| \| cdate \| type: string format: date-time description: Creation timestamp (UTC) readOnly: true \| \| edate \| type: string format: date-time description: Last modification timestamp (UTC) readOnly: true \| |
| Name | Value |
| id | type: string description: System generated unique identifier readOnly: true |
| userEmail * | type: string description: User e-mail address (serves also as username) |
| userFullName * | type: string description: Full name |
| role | $ref: [v202211Role](/v1/docs/user-apis#role) |
| permissions | type: array items: $ref: [v202211PermissionEntry](/v1/docs/user-apis#permissionentry) description: Optional list of permissions granted to the user |
| filter | type: string description: Optional JSON string defining filter for objects visible to the user |
| lastLogin | type: string format: date-time description: UTC Timestamp of user's last login session readOnly: true |
| cdate | type: string format: date-time description: Creation timestamp (UTC) readOnly: true |
| edate | type: string format: date-time description: Last modification timestamp (UTC) readOnly: true |