Create a Principal in a Directory

Creates a new principal identity within the specified directory.
Principals can be configured with metadata and labels for organizational purposes.

post

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Body

application/json

Principal to be created

CreatePrincipalBody

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 | null

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

Response

application/json

Response containing a single principal object

KongPrincipal

A principal represents an authenticated identity within a directory.
Principals can be associated with API keys and inherit metadata from their parent directory.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

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

display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstringrequired

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

<= 255 characters

metadataobject | nullrequired

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.

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/{directoryId}/principals

Body

{}
 
application/json

List all the Principals of a Directory

Retrieves a paginated list of all principals within the specified directory.
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

Path Parameters

directoryIdstring(uuid)required

ID of the directory

Response

application/json

List of Kong Principals

ListKongPrincipals

metaobjectrequired
Show Child Parameters
dataarray[object]required

A principal represents an authenticated identity within a directory.
Principals can be associated with API keys and inherit metadata from their parent directory.

Show Child Parameters
get/directories/{directoryId}/principals
 
application/json

Update a Principal

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

patch

Path Parameters

directoryIdstring(uuid)required

ID of the directory

principalIdstring(uuid)required

Unique identifier of the principal (UUID format)

Body

application/json

Principal to be updated

UpdatePrincipalBody

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 | null

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

Response

application/json

Response containing a single principal object

KongPrincipal

A principal represents an authenticated identity within a directory.
Principals can be associated with API keys and inherit metadata from their parent directory.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

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

display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstringrequired

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

<= 255 characters

metadataobject | nullrequired

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.

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}/principals/{principalId}

Body

{}
 
application/json

Replace a Principal

Completely replaces an existing principal 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

principalIdstring(uuid)required

Unique identifier of the principal (UUID format)

Body

application/json

Principal to be replaced

ReplacePrincipalBody

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 | null

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

Response

application/json

Response containing a single principal object

KongPrincipal

A principal represents an authenticated identity within a directory.
Principals can be associated with API keys and inherit metadata from their parent directory.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

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

display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstringrequired

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

<= 255 characters

metadataobject | nullrequired

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.

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}/principals/{principalId}

Body

{}
 
application/json

Get a Principal

Retrieves detailed information about a specific principal by its ID.

get

Path Parameters

directoryIdstring(uuid)required

ID of the directory

principalIdstring(uuid)required

Unique identifier of the principal (UUID format)

Response

application/json

Response containing a single principal object

KongPrincipal

A principal represents an authenticated identity within a directory.
Principals can be associated with API keys and inherit metadata from their parent directory.

idstring(uuid)requiredread-only

Contains a unique identifier used for this resource.

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

display_namestring

Human-readable name of the principal.

<= 255 characters

descriptionstringrequired

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

<= 255 characters

metadataobject | nullrequired

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.

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}/principals/{principalId}
 
application/json