Authenticate on this directory

Authenticates a credential against the specified directory and returns the resolved principal.
Supports API key and basic auth credential types.
Accepts either a binary Cap’n Proto payload or a JSON payload.

post

Path Parameters

directoryNamestringrequired

Name of the targeted directory

Body

Credential payload to authenticate against the directory.
Accepts either a binary Cap’n Proto payload or a JSON payload.
Schema definition for binary format: https://github.com/kong-konnect/sliver/blob/main/capnp/authrequest.capnp

AuthenticateRequestPayload

AuthenticateRequestPayloadobject

The credential payload used to authenticate a request against the directory.
Use API key authentication to authenticate with an API key, or basic auth to authenticate with a username and password.

One Of
api_keystringrequired

the key to authenticate the principal with.

>= 1 characters

auth_typestringrequired

Allowed values:key_auth

include_consumerboolean

When true, the Kong consumer identity mapped to the resolved principal is included in the response.

workspace_idstring

Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.

Response

Authentication succeeded and the principal was resolved.

AuthResponse

Response returned after a successful authentication operation.
Wraps the resolved principal with cache control metadata.

principalobjectrequired

A principal resolved from the directory. Contains the principal’s identity and metadata.

Show Child Parameters
ttl_secsintegerrequired

Time in seconds the data plane should cache this authentication result.

credential_idstring(uuid)required

The unique identifier of the authenticated credential (API key or basic auth).

consumerobject

The Kong consumer associated with the resolved principal in the given control plane and workspace context.

Show Child Parameters
post/{directoryName}/v2/authenticate

Body

{ "auth_type": "key_auth", "api_key": "my-api-key-secret" }
 

AuthenticateRequestPayload

object

The credential payload used to authenticate a request against the directory.
Use API key authentication to authenticate with an API key, or basic auth to authenticate with a username and password.

One Of
api_keystringrequired

the key to authenticate the principal with.

>= 1 characters

auth_typestringrequired

Allowed values:key_auth

include_consumerboolean

When true, the Kong consumer identity mapped to the resolved principal is included in the response.

workspace_idstring

Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.

Example

AuthenticateRequestPayloadKeyAuth

object

Authenticates a request using an API key credential.

api_keystringrequired

the key to authenticate the principal with.

>= 1 characters

auth_typestringrequired

Allowed values:key_auth

include_consumerboolean

When true, the Kong consumer identity mapped to the resolved principal is included in the response.

workspace_idstring

Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.

Example

AuthenticateRequestPayloadBasicAuth

object

Authenticates a request using a username and password credential.

usernamestringrequired

The username of the principal to authenticate.

>= 1 characters

passwordstringrequired

The password associated with the username.

>= 1 characters

auth_typestringrequired

Allowed values:basic_auth

include_consumerboolean

When true, the Kong consumer identity mapped to the resolved principal is included in the response.

workspace_idstring

Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.

Example

FetchPrincipalRequestPayload

object

The request payload used to look up a principal by a specific identity.

fetch_byOne Of
required

The identity used to look up a principal. The type field determines the identity kind and the required fields.

FetchByOIDCobject

Looks up a principal by matching an OIDC claim name and value.

Show Child Parameters
include_consumerboolean

When true, the Kong consumer identity mapped to the resolved principal is included in the response.

workspace_idstring

Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.

Example