0.0.2OAS 3.0
API Base URL
  • Server 1:https://us.api.konghq.com/v2

    United-States Production region

  • Server 2:https://eu.api.konghq.com/v2

    Europe Production region

  • Server 3:https://au.api.konghq.com/v2

    Australia Production region

  • Server 4:https://me.api.konghq.com/v2

    Middle-East Production region

  • Server 5:https://in.api.konghq.com/v2

    India Production region

  • Server 6:https://sg.api.konghq.com/v2

    Singapore Production region

Security
systemAccountAccessToken (http)

The system account access token is meant for automations and integrations that are not directly associated with a human identity.
You can generate a system account Access Token by creating a system account and then obtaining a system account access token for that account.
The access token must be passed in the header of a request, for example:
curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer spat_i2Ej...'

personalAccessToken (http)

The personal access token is meant to be used as an alternative to basic-auth when accessing Konnect via APIs.
You can generate a Personal Access Token (PAT) from the personal access token page in the Konnect dashboard.
The PAT token must be passed in the header of a request, for example:
curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT...'

konnectAccessToken (http)

The Konnect access token is meant to be used by the Konnect dashboard and the decK CLI authenticate with.

Kong Identity Directories

Use a directory to group consumers around an identity, defined by organizational boundaries,
such as a production directory or a development directory. Directories are connected to a
geographic region in Konnect. Centrally managed consumers defined in
directories can be used across multiple control planes.

Create a new Directory

Creates a new directory for grouping principals around an organizational identity boundary.
Directories can be configured with metadata, labels, and control plane access restrictions.

post

Body

application/json

Directory to be created

CreateDirectoryBody

namestringrequired

Human-readable name of the directory, used to identify the organizational boundary.
A directory name is unique within the organization.

Match pattern:^[a-z0-9-_]+$

>= 1 characters<= 255 characters

descriptionstring

Optional description providing additional context about the directory’s purpose or usage.

<= 255 characters

allowed_control_planesarray[string](uuid)unique-items

List of control plane IDs authorized to make authentication requests to this directory.
Maximum of 32 control planes can be specified. Use allow_all_control_planes for unrestricted access.

Default:[]

allow_all_control_planesboolean

When set to true, all control planes within the organization can make authentication requests to this directory.
This overrides the allowed_control_planes list. Defaults to false for security.

Default:false

ttl_secsinteger

The time in seconds that a principal will be cached in memory on a running Gateway if it is
successfully authenticated from this directory. Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

negative_ttl_secsinteger

If a running Gateway triggers a lookup for a principal that cannot be authenticated in this directory,
a negative_ttl_secs is set. The Gateway will not try to look up the principal in Konnect for negative_ttl_secs seconds.

A principal will be cached for negative_ttl_secs if it does not exist in the directory, or if the provided credentials are invalid.
Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

Response

application/json

A Directory

KongDirectory

A directory represents an organizational boundary for grouping principals and managing their identities.
Directories are region-specific and can control which control planes have authentication access.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7

namestringrequired

Human-readable name of the directory, used to identify the organizational boundary.
A directory name is unique within the organization.

Match pattern:^[a-z0-9-_]+$

>= 1 characters<= 255 characters

descriptionstringrequired

Optional description providing additional context about the directory’s purpose or usage.

<= 255 characters

allowed_control_planesarray[string](uuid)requiredunique-items

List of control plane IDs authorized to make authentication requests to this directory.
Maximum of 32 control planes can be specified. Use allow_all_control_planes for unrestricted access.

Default:[]

allow_all_control_planesbooleanrequired

When set to true, all control planes within the organization can make authentication requests to this directory.
This overrides the allowed_control_planes list. Defaults to false for security.

Default:false

ttl_secsintegerrequired

The time in seconds that a principal will be cached in memory on a running Gateway if it is
successfully authenticated from this directory. Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

negative_ttl_secsintegerrequired

If a running Gateway triggers a lookup for a principal that cannot be authenticated in this directory,
a negative_ttl_secs is set. The Gateway will not try to look up the principal in Konnect for negative_ttl_secs seconds.

A principal will be cached for negative_ttl_secs if it does not exist in the directory, or if the provided credentials are invalid.
Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

labelsobjectrequired

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

created_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity creation date.

Example:2022-11-04T20:10:06.927Z

updated_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity update date.

Example:2022-11-04T20:10:06.927Z

post/directories

Body

{ "name": "name" }
 
application/json

List all directories

Retrieves a paginated list of all available directories in the organization.
Results can be sorted by name, created_at, or updated_at.

get

Query Parameters

page[size]integer

The maximum number of items to include per page. The last page of a collection may include fewer items.

Example:10

page[before]string

Request the next page of data, starting with the item before this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

page[after]string

Request the next page of data, starting with the item after this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

sortstring

The asc suffix is optional as the default sort order is ascending.
The desc suffix is used to specify a descending order.
Multiple sort attributes may be provided via a comma separated list.
JSONPath notation may be used to specify a sub-attribute (eg: ‘foo.bar desc’).

Example:created_at desc

Response

application/json

List of Directories

ListKongDirectories

metaobjectrequired
Show Child Parameters
dataarray[object]required

A directory represents an organizational boundary for grouping principals and managing their identities.
Directories are region-specific and can control which control planes have authentication access.

Show Child Parameters
get/directories
 
application/json

Update a Directory

Partially updates an existing directory by modifying only the provided fields.
Unspecified fields will retain their current values.

patch

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Body

application/json

Request body for partially updating a directory

UpdateDirectoryBody

namestring

Human-readable name of the directory, used to identify the organizational boundary.
A directory name is unique within the organization.

Match pattern:^[a-z0-9-_]+$

>= 1 characters<= 255 characters

allowed_control_planesarray[string](uuid)unique-items

List of control plane IDs authorized to make authentication requests to this directory.
Maximum of 32 control planes can be specified. Use allow_all_control_planes for unrestricted access.

Default:[]

allow_all_control_planesboolean

When set to true, all control planes within the organization can make authentication requests to this directory.
This overrides the allowed_control_planes list. Defaults to false for security.

Default:false

ttl_secsinteger

The time in seconds that a principal will be cached in memory on a running Gateway if it is
successfully authenticated from this directory. Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

negative_ttl_secsinteger

If a running Gateway triggers a lookup for a principal that cannot be authenticated in this directory,
a negative_ttl_secs is set. The Gateway will not try to look up the principal in Konnect for negative_ttl_secs seconds.

A principal will be cached for negative_ttl_secs if it does not exist in the directory, or if the provided credentials are invalid.
Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

Response

application/json

A Directory

KongDirectory

A directory represents an organizational boundary for grouping principals and managing their identities.
Directories are region-specific and can control which control planes have authentication access.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7

namestringrequired

Human-readable name of the directory, used to identify the organizational boundary.
A directory name is unique within the organization.

Match pattern:^[a-z0-9-_]+$

>= 1 characters<= 255 characters

descriptionstringrequired

Optional description providing additional context about the directory’s purpose or usage.

<= 255 characters

allowed_control_planesarray[string](uuid)requiredunique-items

List of control plane IDs authorized to make authentication requests to this directory.
Maximum of 32 control planes can be specified. Use allow_all_control_planes for unrestricted access.

Default:[]

allow_all_control_planesbooleanrequired

When set to true, all control planes within the organization can make authentication requests to this directory.
This overrides the allowed_control_planes list. Defaults to false for security.

Default:false

ttl_secsintegerrequired

The time in seconds that a principal will be cached in memory on a running Gateway if it is
successfully authenticated from this directory. Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

negative_ttl_secsintegerrequired

If a running Gateway triggers a lookup for a principal that cannot be authenticated in this directory,
a negative_ttl_secs is set. The Gateway will not try to look up the principal in Konnect for negative_ttl_secs seconds.

A principal will be cached for negative_ttl_secs if it does not exist in the directory, or if the provided credentials are invalid.
Maximum is 86400 seconds (24 hours).

Default:600

>= 300<= 86400

labelsobjectrequired

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

created_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity creation date.

Example:2022-11-04T20:10:06.927Z

updated_atstring(date-time)requiredread-only

An ISO-8601 timestamp representation of entity update date.

Example:2022-11-04T20:10:06.927Z

patch/directories/{directoryId}

Body

{}
 
application/json