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.
Query Parameters
The maximum number of items to include per page. The last page of a collection may include fewer items.
Example:10
Request the next page of data, starting with the item before this parameter.
Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ
Request the next page of data, starting with the item after this parameter.
Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ
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
Response
List of Directories
ListKongDirectories
Show Child Parameters
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
Authentication
Query Parameters
Update a Directory
Partially updates an existing directory by modifying only the provided fields.
Unspecified fields will retain their current values.
Path Parameters
ID of the directory
Body
application/json
Body
Request body for partially updating a directory
UpdateDirectoryBody
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
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:[]
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
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
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
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
Response
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
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
Optional description providing additional context about the directory’s purpose or usage.
<= 255 characters
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:[]
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
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
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
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"}
An ISO-8601 timestamp representation of entity creation date.
Example:2022-11-04T20:10:06.927Z
An ISO-8601 timestamp representation of entity update date.
Example:2022-11-04T20:10:06.927Z
Authentication
Path Parameters
Body
Replace a Directory
Completely replaces an existing directory with the provided data.
All fields must be specified; any omitted fields will be reset to their defaults.
Path Parameters
ID of the directory
Body
application/json
Body
Directory to be replaced
ReplaceDirectoryBody
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
Optional description providing additional context about the directory’s purpose or usage.
<= 255 characters
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:[]
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
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
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
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
Response
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
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
Optional description providing additional context about the directory’s purpose or usage.
<= 255 characters
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:[]
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
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
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
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"}
An ISO-8601 timestamp representation of entity creation date.
Example:2022-11-04T20:10:06.927Z
An ISO-8601 timestamp representation of entity update date.
Example:2022-11-04T20:10:06.927Z
Authentication
Path Parameters
Body
Get a Directory
Retrieves detailed information about a specific directory by its ID.
Path Parameters
ID of the directory
Response
application/json
Response
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
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
Optional description providing additional context about the directory’s purpose or usage.
<= 255 characters
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:[]
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
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
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
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"}
An ISO-8601 timestamp representation of entity creation date.
Example:2022-11-04T20:10:06.927Z
An ISO-8601 timestamp representation of entity update date.
Example:2022-11-04T20:10:06.927Z
Authentication
Path Parameters
Delete a Directory
Deletes a directory and optionally all its associated resources (principals, keys, etc.).
Use the force parameter to control deletion behavior when dependencies exist.
Query Parameters
If true, delete the specified directory and all its associated resources. If false, only allow deletion if no clients, scopes or claims are associated with the auth server.
Allowed values:truefalse
Default:false
Path Parameters
ID of the directory
Response
Response
Success