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

Delete a Principal

Permanently deletes a principal from the directory.

delete

Path Parameters

directoryIdstring(uuid)required

ID of the directory

principalIdstring(uuid)required

Unique identifier of the principal (UUID format)

Response

Success

delete/directories/{directoryId}/principals/{principalId}
 

KongPrincipalCredential

Credentials are authentication secrets associated with principals. Supported credential types are
API keys (system-generated or imported) and basic auth username/password pairs.

List all basic auth credentials

Retrieves a paginated list of all basic auth credentials associated with the specified principal.

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

Path Parameters

directoryIdstring(uuid)required

ID of the directory

principalIdstring(uuid)required

Unique identifier of the principal (UUID format)

Response

application/json

List of basic auth credentials

ListKongBasicAuths

metaobjectrequired
Show Child Parameters
dataarray[object]required

A basic auth credential associated with a principal, enabling username/password authentication.

Show Child Parameters
get/directories/{directoryId}/principals/{principalId}/basic-auths
 
application/json