User APIs

  • Updated on Aug 15, 2025
  • Published on Jul 18, 2025
  • 4 minute(s) read
Prev Next

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

Notes:

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

  • Protobuf and OpenAPI specifications for Kentik’s v6 APIs are available in our 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).

  • User permissions: Permissions granting access to specific capabilities of the Kentik platform (see User Permissions).

Both REST endpoint and gRPC RPCs are provided.

Note: The legacy REST-only 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: 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). 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: To test methods using your own Kentik data, use the portal's 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

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
Parameters:
None

Response body:
v202211CreateUserResponse

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


Parameters:

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

Parameters:

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.


Parameters:

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


Parameters:

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


Parameters:

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

rpcStatus

Schema: rpcStatus

Type: object

Properties:

Name

Value

code

type: integer

format: int32

message

type: string

details

type: array

items: $ref: protobufAny

CreateUserRequest

Schema: v202211CreateUserRequest

Type: object

Properties:

Name

Value

user

$ref: v202211User

CreateUserResponse

Schema: v202211CreateUserResponse

Type: object

Properties:

Name

Value

user

$ref: v202211User

DeleteUserResponse

Schema: v202211DeleteUserResponse

Type: object

Properties: None.

GetUserResponse

Schema: v202211GetUserResponse

Type: object

Properties:

Name

Value

user

$ref: v202211User

ListUsersResponse

Schema: v202211ListUsersResponse

Type: object

Properties:

Name

Value

users

type: array

items: $ref: v202211User

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

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

UpdateUserRequest

Schema: v202211UpdateUserRequest

Type: object

Properties:

Name

Value

user

$ref: v202211User

UpdateUserResponse

Schema: v202211UpdateUserResponse

Type: object

Properties:

Name

Value

user

$ref: v202211User

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

permissions

type: array

items: $ref: v202211PermissionEntry

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

Related articles