v28

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-263064641.4 MB

Kong Identity Directories

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/v2/directories

Request body

namestring required

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

descriptionstring

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

allowed_control_planesstring[]

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.

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.

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).

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).

labelsLabels

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 "_".

managed_byManagedBy

Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, terraform).

Keys must be 1–63 characters long and start with an alphanumeric character.

Example request

{
  "labels": {
    "env": "test"
  },
  "managed_by": {
    "owner": "terraform"
  }
}

Response

A Directory

idstring uuid required

Contains a unique identifier used for this resource.

namestring required

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

descriptionstring required

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

allowed_control_planesstring[] required

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.

allow_all_control_planesboolean required

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.

ttl_secsinteger required

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).

negative_ttl_secsinteger required

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).

labelsLabels required

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 "_".

managed_byManagedBy required

Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, terraform).

Keys must be 1–63 characters long and start with an alphanumeric character.

created_atstring date-time required

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity update date.

Example response

{
  "id": "5f9fd312-a987-4628-b4c5-bb4f4fddd5f7",
  "labels": {
    "env": "test"
  },
  "managed_by": {
    "owner": "terraform"
  },
  "created_at": "2022-11-04T20:10:06.927Z",
  "updated_at": "2022-11-04T20:10:06.927Z"
}