CreateDirectoryBody

object
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:[]

>= 0 items<= 32 items

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

Example

ReplaceDirectoryBody

object
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:[]

>= 0 items<= 32 items

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

Example

UpdateDirectoryBody

object
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:[]

>= 0 items<= 32 items

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

Example

CreatePrincipalBody

object
display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstring

Optional description providing additional context about the principal’s purpose or role.

<= 255 characters

metadataobject

A map of metadata key-value pairs associated with this entity. This metadata is passed to the data plane
to enrich the execution context. During authentication, metadata is inherited and overridden in a hierarchical
manner: Directory metadata is inherited by Principals, which is then inherited and overridden by Credentials.

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

Example

ReplacePrincipalBody

object
display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstring

Optional description providing additional context about the principal’s purpose or role.

<= 255 characters

metadataobject

A map of metadata key-value pairs associated with this entity. This metadata is passed to the data plane
to enrich the execution context. During authentication, metadata is inherited and overridden in a hierarchical
manner: Directory metadata is inherited by Principals, which is then inherited and overridden by Credentials.

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

Example