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.

put

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Body

application/json

Directory to be replaced

ReplaceDirectoryBody

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

put/directories/{directoryId}

Body

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

Get a Directory

Retrieves detailed information about a specific directory by its ID.

get

Path Parameters

directoryIdstring(uuid)required

ID of the directory

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

get/directories/{directoryId}
 
application/json

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.

delete

Query Parameters

forcestring

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

directoryIdstring(uuid)required

ID of the directory

Response

Success

delete/directories/{directoryId}
 

Get the realm configuration of a Directory

Retrieves the realm configuration values for the specified directory.

get

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Response

application/json

Realm configuration values for a directory

KongDirectoryRealmValues

Configuration values used when a Kong v3 data plane connects to identity as realm. The directory is used as a realm for regional consumers.

ttlintegerrequired

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlintegerrequired

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

consumer_groupsarray[string](set)requiredunique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

get/directories/{directoryId}/realm-config
 
application/json

Replace Directory realm configuration

Completely replaces the realm configuration for the specified directory.
All fields must be specified; any omitted fields will be reset to their defaults.

put

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Body

application/json

Realm configuration to be replaced

KongDirectoryRealmValues

Configuration values used when a Kong v3 data plane connects to identity as realm. The directory is used as a realm for regional consumers.

ttlintegerrequired

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlintegerrequired

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

consumer_groupsarray[string](set)requiredunique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

Response

application/json

Realm configuration values for a directory

KongDirectoryRealmValues

Configuration values used when a Kong v3 data plane connects to identity as realm. The directory is used as a realm for regional consumers.

ttlintegerrequired

The time in minutes that the Consumer will be cached in memory on a running Gateway if it is
successfully loaded from Konnect.

Default:10

>= 5

negative_ttlintegerrequired

If a running Gateway triggers a lookup for a Consumer that cannot be authenticated this realm, a negative_ttl
is set. The Gateway will not try to lookup the Consumer in Konnect for negative_ttl minutes.

A Consumer will be cached for negative_ttl if they do not exist in the Realm, or if the provided credentials
are invalid.

Default:10

>= 5

consumer_groupsarray[string](set)requiredunique-items

A list of consumer groups to automatically add to any consumers created within this Realm.
If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

put/directories/{directoryId}/realm-config

Body

{ "ttl": 10, "negative_ttl": 10, "consumer_groups": [] }
 
application/json