Konnect APIs
What are the Konnect APIs?
The Konnect APIs allow you to manage your ecosystem, including Kong Gateway configuration management, Analytics, Dev Portal, and more.
Konnect API authentication
The recommended method of authentication for Konnect is an access token. There are two types of access tokens available for Konnect:
- Personal access tokens associated with user accounts, generated using the personal access token page in Konnect.
- System account access tokens associated with system accounts, generated using the system accounts page. or the Identity API
The access token must be passed in the Authorization
header of all requests, for example:
curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT'
Personal access tokens
Personal access tokens (PATs) let you access the Konnect API and CLIs as your personal user account. They are useful for admin tasks, and are the most commonly used and recommended token type.
When using a PAT, be aware of the following:
- A PAT is granted all of the permissions that the user has access to via their most up-to-date role assignment.
- The PAT has a maximum duration of 12 months.
- There is a limit of 10 personal access tokens per user.
- Unused tokens are deleted and revoked after 12 months of inactivity.
System accounts and access tokens
A system account is a service account in Konnect, meant to be used for automation and integrations:
- System accounts are intended to be used with APIs and CLIs. They don’t have sign-in credentials and can’t access the Konnect UI.
- System accounts are not associated with an email address, so they aren’t attached to any person’s identity.
- When you use a user account as part of an automation or integration and that user leaves the company, automation and integrations break. If you use a system account instead, the automation and integrations wouldn’t break.
An access token created by a system account inherits the roles assigned to the system account, and can be assigned roles directly or inherit the roles of a team.
Managed system accounts
Managed system accounts, denoted by konnect_managed:true
in the Identity API, are system accounts whose lifecycle is managed by Konnect instead of the user.
Mesh Manager automatically creates a managed system account that is only used to issue a token during the zone creation process. This managed system account can’t be edited or deleted manually. Instead, it is deleted automatically by Konnect when the zone is deleted.
Access token expiration
When a token is about to expire, a notification email is sent to all users who have the create
permission for tokens in the org.
By default, the following notifications are sent:
- Expiring: Reminders are sent 14 days, 7 days, and 1 day before the token expiration date.
- Expired: A notification is sent once the token has expired.
Each user can toggle these notifications on or off in the org notification settings for personal and system access tokens. The timing and target email for the notifications can’t be changed.
Konnect API filtering
The Konnect APIs support the ability to filter over selected collections and only return results that you are interested in.
Not every filter operation described here is available in every Konnect API. Specific APIs may support a subset of these options. For the most accurate information on available filters for each API endpoint, always refer to the individual API specification.
Available fields
-
Users:
id
,email
,full_name
,active
-
Teams:
id
,name
,system_team
-
Assigned Roles:
role
,entity_type
,entity_region
,entity_id
Numeric and timestamp fields
When matching against both numeric and timestamp fields, you can filter in the following formats:
-
Equal:
?filter[field][eq]=value
or?filter[field]=value
-
Contains:
?filter[field][contains]=value
-
Less Than:
?filter[field][lt]=value
-
Less Than or Equal:
?filter[field][lte]=value
-
Greater Than:
?filter[field][gt]=value
-
Greater Than or Equal:
?filter[field][gte]=value
If the qualifier is omitted, ?filter[field]=value
for example, the filtering behavior will perform an exact style equal match.
Filtering examples
The examples in the table below filter the following response:
{
"data": [
{
"id": "500d74f4-37e1-4f59-b51a-8cf7c7903692",
"email": "CharlieCruz@konghq.com",
"name": "Charlie",
"full_name": "Charlie Cruz",
"active": true,
"created_at": "2022-05-10T15:10:25Z"
},
{
"id": "500d74f4-37e1-4b13-b51a-8cf7c7903692",
"email": "AlexCruz@konghq.com",
"name": "Alex",
"full_name": "Alex Cruz",
"active": true,
"created_at": "2022-05-10T15:10:25Z",
"updated_at": "2022-10-19T15:33:02Z"
},
{
"id": "500d74f4-37e1-4d13-b51a-8cf7c7903692",
"email": "AlexGarcia@konghq.com",
"name": "Alex",
"full_name": "Alex Garcia",
"active": true,
"created_at": "2022-05-10T15:10:25Z",
"updated_at": "2022-10-19T15:33:02Z"
}
]
}
Filter |
Result |
---|---|
Filter on a single parameter:
|
|
Filter on multiple parameters:
|
|
Filter on the existence of a key:
|
|