Konnect APIs

The Konnect APIs allow you to manage your ecosystem, including Kong Gateway configuration management, Analytics, Dev Portal, and more.

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.

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.

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.

• Users: id, email, full_name, active
• Teams: id, name, system_team
• Assigned Roles: role,entity_type, entity_region, entity_id

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.

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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "data": [
    {
      "id": "500d74f4-37e1-4f59-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"
    }
  ]
}

{
  "data": [
    {
      "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"
    }
  ]
}