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.
Path Parameters
ID of the directory
Body
application/json
Body
Principal to be created
CreatePrincipalBody
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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
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.
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
Path Parameters
ID of the directory
Response
application/json
Response
List of Kong Principals
ListKongPrincipals
Show Child Parameters
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
Authentication
Path Parameters
Query Parameters
Update a Principal
Partially updates an existing principal by modifying only the provided fields.
Unspecified fields will retain their current values.
Path Parameters
ID of the directory
Unique identifier of the principal (UUID format)
Body
application/json
Body
Principal to be updated
UpdatePrincipalBody
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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 Principal
Completely replaces an existing principal with the provided data.
All fields must be specified; any omitted fields will be reset to their defaults.
Path Parameters
ID of the directory
Unique identifier of the principal (UUID format)
Body
application/json
Body
Principal to be replaced
ReplacePrincipalBody
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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 Principal
Retrieves detailed information about a specific principal by its ID.
Path Parameters
ID of the directory
Unique identifier of the principal (UUID format)
Response
application/json
Response
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.
Contains a unique identifier used for this resource.
Example:5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
Human-readable name of the principal.
<= 255 characters
Optional description providing additional context about the principal’s purpose or role.
<= 255 characters
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.
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