---
title: "Konnect Kong Identity auth api"
url: "https://nov18-dev.movespot.fyi/apis/konnect-kong-identity-auth-api-dev-0/versions/95ca6cb9-c471-4475-a351-61326ecea57b"
---

# Konnect Kong Identity auth api

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Konnect Kong Identity auth api","version":"0.0.2"},"servers":[{"url":"https://us.api.konghq.com","description":"United-States Production region"},{"url":"https://eu.api.konghq.com","description":"Europe Production region"},{"url":"https://au.api.konghq.com","description":"Australia Production region"},{"url":"https://me.api.konghq.com","description":"Middle-East Production region"},{"url":"https://in.api.konghq.com","description":"India Production region"},{"url":"https://sg.api.konghq.com","description":"Singapore Production region"}],"paths":{"/{directoryName}/v2/fetch-principal":{"parameters":[{"$ref":"#/components/parameters/directoryName"}],"post":{"operationId":"fetch-principal-from-directory","summary":"Fetch a principal from a directory","description":"Retrieves a principal from the specified directory by a key/value lookup.\nUsed by the data plane to resolve a principal during request processing.\nAccepts either a binary Cap'n Proto payload or a JSON payload.\n","requestBody":{"$ref":"#/components/requestBodies/FetchPrincipal"},"responses":{"200":{"description":"The principal was found and returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchPrincipalResponse"},"examples":{"fetchedPrincipal":{"summary":"A resolved principal","value":{"principal":{"id":"12345678-1234-1234-1234-123456789012","display_name":"my-service","metadata":{"consumer_type":"service","env":"production"},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"},"ttl_secs":600}},"fetchedPrincipalWithConsumer":{"summary":"A resolved principal with its consumer identity","value":{"principal":{"id":"12345678-1234-1234-1234-123456789012","display_name":"my-service","metadata":{"consumer_type":"service"},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"},"ttl_secs":600,"consumer":{"id":"c1f5b3e2-1234-4abc-8def-000000000001","control_plane_id":"cp-abc123","workspace_id":"ws-def456"}}}}},"application/octet-stream":{"schema":{"description":"Binary Cap'n Proto encoded fetch-principal response.\nSchema definition: https://github.com/kong-konnect/sliver/blob/main/capnp/fetchprincipalresponse.capnp\n","type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/{directoryName}/v2/authenticate":{"parameters":[{"$ref":"#/components/parameters/directoryName"}],"post":{"operationId":"authenticate-in-directory","summary":"Authenticate on this directory","description":"Authenticates a credential against the specified directory and returns the resolved principal.\nSupports API key and basic auth credential types.\nAccepts either a binary Cap'n Proto payload or a JSON payload.\n","requestBody":{"$ref":"#/components/requestBodies/Authenticate"},"responses":{"200":{"description":"Authentication succeeded and the principal was resolved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"},"examples":{"authenticatedPrincipal":{"summary":"A successfully authenticated principal","value":{"principal":{"id":"12345678-1234-1234-1234-123456789012","display_name":"my-service","metadata":{"consumer_type":"service","env":"production"},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"},"ttl_secs":600,"credential_id":"abcdef01-abcd-abcd-abcd-abcdef012345"}},"authenticatedPrincipalWithConsumer":{"summary":"A successfully authenticated principal with its consumer identity","value":{"principal":{"id":"12345678-1234-1234-1234-123456789012","display_name":"my-service","metadata":{"consumer_type":"service"},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"},"ttl_secs":600,"credential_id":"abcdef01-abcd-abcd-abcd-abcdef012345","consumer":{"id":"c1f5b3e2-1234-4abc-8def-000000000001","control_plane_id":"cp-abc123","workspace_id":"ws-def456"}}}}},"application/octet-stream":{"schema":{"description":"Binary Cap'n Proto encoded auth response.\nSchema definition: https://github.com/kong-konnect/sliver/blob/main/capnp/authresponse.capnp\n","type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"parameters":{"directoryName":{"name":"directoryName","in":"path","required":true,"description":"Name of the targeted directory","schema":{"type":"string"}}},"schemas":{"AuthenticateRequestPayload":{"description":"The credential payload used to authenticate a request against the directory.\nUse API key authentication to authenticate with an API key, or basic auth to authenticate with a username and password.\n","type":"object","discriminator":{"propertyName":"auth_type","mapping":{"key_auth":"#/components/schemas/AuthenticateRequestPayloadKeyAuth","basic_auth":"#/components/schemas/AuthenticateRequestPayloadBasicAuth"}},"oneOf":[{"$ref":"#/components/schemas/AuthenticateRequestPayloadKeyAuth"},{"$ref":"#/components/schemas/AuthenticateRequestPayloadBasicAuth"}]},"AuthenticateRequestPayloadKeyAuth":{"description":"Authenticates a request using an API key credential.\n","type":"object","properties":{"api_key":{"description":"the key to authenticate the principal with.","type":"string","minLength":1},"auth_type":{"type":"string","enum":["key_auth"]},"include_consumer":{"description":"When true, the Kong consumer identity mapped to the resolved principal is included in the response.\n","type":"boolean"},"workspace_id":{"description":"Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.\n","type":"string"}},"required":["api_key","auth_type"]},"AuthenticateRequestPayloadBasicAuth":{"description":"Authenticates a request using a username and password credential.\n","type":"object","properties":{"username":{"description":"The username of the principal to authenticate.","type":"string","minLength":1},"password":{"description":"The password associated with the username.","type":"string","minLength":1},"auth_type":{"type":"string","enum":["basic_auth"]},"include_consumer":{"description":"When true, the Kong consumer identity mapped to the resolved principal is included in the response.\n","type":"boolean"},"workspace_id":{"description":"Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.\n","type":"string"}},"required":["username","password","auth_type"]},"FetchPrincipalRequestPayload":{"description":"The request payload used to look up a principal by a specific identity.\n","type":"object","properties":{"fetch_by":{"$ref":"#/components/schemas/FetchBy"},"include_consumer":{"description":"When true, the Kong consumer identity mapped to the resolved principal is included in the response.\n","type":"boolean"},"workspace_id":{"description":"Scopes the consumer lookup to a specific workspace within the control plane. Applicable only when include_consumer is true.\n","type":"string"}},"required":["fetch_by"]},"FetchBy":{"description":"The identity used to look up a principal. The `type` field determines the identity kind and the required fields.\n","discriminator":{"propertyName":"type","mapping":{"oidc":"#/components/schemas/FetchByOIDC","consumer":"#/components/schemas/FetchByConsumer","custom":"#/components/schemas/FetchByCustom","principal_id":"#/components/schemas/FetchByPrincipalID"}},"oneOf":[{"$ref":"#/components/schemas/FetchByOIDC"},{"$ref":"#/components/schemas/FetchByConsumer"},{"$ref":"#/components/schemas/FetchByCustom"},{"$ref":"#/components/schemas/FetchByPrincipalID"}]},"FetchByOIDC":{"description":"Looks up a principal by matching an OIDC claim name and value.","type":"object","properties":{"type":{"type":"string","enum":["oidc"]},"issuer":{"description":"The OIDC issuer URL that issued the claims.","type":"string","format":"uri","minLength":1},"claim":{"type":"object","properties":{"name":{"description":"The name of the OIDC claim to match against.","type":"string","minLength":1},"value":{"description":"The expected value of the OIDC claim.","type":"string","minLength":1}},"required":["name","value"]}},"required":["type","claim","issuer"]},"FetchByPrincipalID":{"description":"Looks up a principal by its unique principal ID.","type":"object","properties":{"type":{"type":"string","enum":["principal_id"]},"principal_id":{"description":"The unique identifier of the principal to fetch.","type":"string","format":"uuid"}},"required":["type","principal_id"]},"FetchByConsumer":{"description":"Looks up a principal by a Kong consumer ID for the requesting control-plane.","type":"object","properties":{"type":{"type":"string","enum":["consumer"]},"consumer_id":{"description":"The unique identifier of the Kong consumer.","type":"string","minLength":1},"workspace_id":{"description":"The workspace ID within the control plane.","type":"string"}},"required":["type","consumer_id"]},"FetchByCustom":{"description":"Looks up a principal by an arbitrary key/value pair.","type":"object","properties":{"type":{"type":"string","enum":["custom"]},"key":{"description":"The custom key to match against.","type":"string","minLength":1},"value":{"description":"The value of the identity to match against.","type":"string","minLength":1}},"required":["type","key","value"]},"AuthResponse":{"description":"Response returned after a successful authentication operation.\nWraps the resolved principal with cache control metadata.\n","type":"object","properties":{"principal":{"$ref":"#/components/schemas/Principal"},"ttl_secs":{"description":"Time in seconds the data plane should cache this authentication result.\n","type":"integer"},"credential_id":{"description":"The unique identifier of the authenticated credential (API key or basic auth).","type":"string","format":"uuid"},"consumer":{"$ref":"#/components/schemas/ConsumerIdentity"}},"required":["principal","ttl_secs","credential_id"]},"FetchPrincipalResponse":{"description":"Response returned after a successful fetch-principal operation.\nWraps the resolved principal with cache control metadata.\n","type":"object","properties":{"principal":{"$ref":"#/components/schemas/Principal"},"ttl_secs":{"description":"Time in seconds the data plane should cache this result.\n","type":"integer"},"consumer":{"$ref":"#/components/schemas/ConsumerIdentity"}},"required":["principal","ttl_secs"]},"ConsumerIdentity":{"description":"The Kong consumer associated with the resolved principal in the given control plane and workspace context.\n","type":"object","properties":{"id":{"description":"The unique identifier of the Kong consumer.","type":"string"},"control_plane_id":{"description":"The Kong control plane this consumer belongs to.","type":"string"},"workspace_id":{"description":"The workspace within the control plane, if applicable.","type":"string","nullable":true}},"required":["id","control_plane_id"]},"Principal":{"description":"A principal resolved from the directory. Contains the principal's identity and metadata.\n","type":"object","properties":{"id":{"$ref":"#/components/schemas/UUID"},"display_name":{"description":"Human-readable name of the principal.","type":"string"},"metadata":{"$ref":"#/components/schemas/KongIdentityMetadata"},"created_at":{"$ref":"#/components/schemas/CreatedAt"},"updated_at":{"$ref":"#/components/schemas/UpdatedAt"}},"required":["id","display_name","metadata","created_at","updated_at"]},"UnauthorizedError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","required":["negative_ttl_secs"],"properties":{"status":{"example":401},"title":{"example":"Unauthorized"},"type":{"example":"https://httpstatuses.com/401"},"instance":{"example":"kong:trace:1234567890"},"detail":{"example":"Invalid credentials"},"negative_ttl_secs":{"description":"Time in seconds the data plane should cache this authentication failure.\nMirrors the directory-level negative_ttl_secs setting.\nZero means no caching hint.\n","type":"integer","example":0}}}]},"UUID":{"description":"Contains a unique identifier used for this resource.","type":"string","format":"uuid","example":"5f9fd312-a987-4628-b4c5-bb4f4fddd5f7","readOnly":true},"KongIdentityMetadata":{"description":"A map of metadata key-value pairs associated with this entity. This metadata is passed to the data plane \nto enrich the execution context. During authentication, metadata is inherited and overridden in a hierarchical \nmanner: Directory metadata is inherited by Principals, which is then inherited and overridden by Credentials.\n","type":"object","additionalProperties":{"oneOf":[{"type":"string","format":"date-time"},{"type":"boolean"},{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"},"minItems":0,"maxItems":255,"uniqueItems":true},{"type":"array","items":{"type":"integer"},"minItems":0,"maxItems":255,"uniqueItems":true}]},"maxProperties":50,"minProperties":0,"nullable":true},"CreatedAt":{"description":"An ISO-8601 timestamp representation of entity creation date.","type":"string","format":"date-time","example":"2022-11-04T20:10:06.927Z","readOnly":true},"UpdatedAt":{"description":"An ISO-8601 timestamp representation of entity update date.","type":"string","format":"date-time","example":"2022-11-04T20:10:06.927Z","readOnly":true},"BaseError":{"description":"standard error","type":"object","properties":{"status":{"description":"The HTTP status code of the error. Useful when passing the response\nbody to child properties in a frontend UI. Must be returned as an integer.\n","type":"integer","readOnly":true},"title":{"description":"A short, human-readable summary of the problem. It should not\nchange between occurences of a problem, except for localization.\nShould be provided as \"Sentence case\" for direct use in the UI.\n","type":"string","readOnly":true},"type":{"description":"The error type.","type":"string","readOnly":true},"instance":{"description":"Used to return the correlation ID back to the user, in the format\nkong:trace:<correlation_id>. This helps us find the relevant logs\nwhen a customer reports an issue.\n","type":"string","readOnly":true},"detail":{"description":"A human readable explanation specific to this occurence of the problem.\nThis field may contain request/entity data to help the user understand\nwhat went wrong. Enclose variable values in square brackets. Should be\nprovided as \"Sentence case\" for direct use in the UI.\n","type":"string","readOnly":true}},"required":["status","title","instance","detail"],"title":"Error"},"InvalidRules":{"description":"invalid parameters rules","type":"string","enum":["required","is_array","is_base64","is_boolean","is_date_time","is_integer","is_null","is_number","is_object","is_string","is_uuid","is_fqdn","is_arn","unknown_property","missing_reference","is_label","matches_regex","invalid","is_supported_network_availability_zone_list","is_supported_network_cidr_block","is_supported_provider_region","type"],"nullable":true,"readOnly":true},"InvalidParameterStandard":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"$ref":"#/components/schemas/InvalidRules"},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"is a required field","readOnly":true}},"additionalProperties":false,"required":["field","reason"]},"InvalidParameterMinimumLength":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["min_length","min_digits","min_lowercase","min_uppercase","min_symbols","min_items","min"],"nullable":false,"readOnly":true},"minimum":{"type":"integer","example":8},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"must have at least 8 characters","readOnly":true}},"additionalProperties":false,"required":["field","reason","rule","minimum"]},"InvalidParameterMaximumLength":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["max_length","max_items","max"],"nullable":false,"readOnly":true},"maximum":{"type":"integer","example":8},"source":{"type":"string","example":"body"},"reason":{"type":"string","example":"must not have more than 8 characters","readOnly":true}},"additionalProperties":false,"required":["field","reason","rule","maximum"]},"InvalidParameterChoiceItem":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["enum"],"nullable":false,"readOnly":true},"reason":{"type":"string","example":"is a required field","readOnly":true},"choices":{"type":"array","items":{},"minItems":1,"nullable":false,"readOnly":true,"uniqueItems":true},"source":{"type":"string","example":"body"}},"additionalProperties":false,"required":["field","reason","rule","choices"]},"InvalidParameterDependentItem":{"type":"object","properties":{"field":{"type":"string","example":"name","readOnly":true},"rule":{"description":"invalid parameters rules","type":"string","enum":["dependent_fields"],"nullable":true,"readOnly":true},"reason":{"type":"string","example":"is a required field","readOnly":true},"dependents":{"type":"array","items":{},"nullable":true,"readOnly":true,"uniqueItems":true},"source":{"type":"string","example":"body"}},"additionalProperties":false,"required":["field","rule","reason","dependents"]},"InvalidParameters":{"description":"invalid parameters","type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/InvalidParameterStandard"},{"$ref":"#/components/schemas/InvalidParameterMinimumLength"},{"$ref":"#/components/schemas/InvalidParameterMaximumLength"},{"$ref":"#/components/schemas/InvalidParameterChoiceItem"},{"$ref":"#/components/schemas/InvalidParameterDependentItem"}]},"minItems":1,"nullable":false,"uniqueItems":true},"BadRequestError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","required":["invalid_parameters"],"properties":{"invalid_parameters":{"$ref":"#/components/schemas/InvalidParameters"}}}]},"ForbiddenError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","properties":{"status":{"example":403},"title":{"example":"Forbidden"},"type":{"example":"https://httpstatuses.com/403"},"instance":{"example":"kong:trace:1234567890"},"detail":{"example":"Forbidden"}}}]},"NotFoundError":{"allOf":[{"$ref":"#/components/schemas/BaseError"},{"type":"object","properties":{"status":{"example":404},"title":{"example":"Not Found"},"type":{"example":"https://httpstatuses.com/404"},"instance":{"example":"kong:trace:1234567890"},"detail":{"example":"Not found"}}}]}},"examples":{"UnauthorizedExample":{"value":{"status":401,"title":"Unauthorized","instance":"kong:trace:8347343766220159418","detail":"Unauthorized","negative_ttl_secs":0}},"ForbiddenExample":{"value":{"status":403,"title":"Forbidden","instance":"kong:trace:2723154947768991354","detail":"You do not have permission to perform this action"}},"NotFoundExample":{"value":{"status":404,"title":"Not Found","instance":"kong:trace:6816496025408232265","detail":"Not Found"}}},"requestBodies":{"Authenticate":{"description":"Credential payload to authenticate against the directory.\nAccepts either a binary Cap'n Proto payload or a JSON payload.\nSchema definition for binary format: https://github.com/kong-konnect/sliver/blob/main/capnp/authrequest.capnp\n","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateRequestPayload"},"examples":{"keyAuth":{"summary":"Authenticate with an API key","value":{"auth_type":"key_auth","api_key":"my-api-key-secret"}},"basicAuth":{"summary":"Authenticate with username and password","value":{"auth_type":"basic_auth","username":"my-service","password":"my-password-secret"}}}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"FetchPrincipal":{"description":"Lookup payload to fetch a principal from the directory by a key/value pair.\nAccepts either a binary Cap'n Proto payload or a JSON payload.\nSchema definition for binary format: https://github.com/kong-konnect/sliver/blob/main/capnp/fetchprincipal.capnp\n","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchPrincipalRequestPayload"},"examples":{"fetchByOIDC":{"summary":"Fetch a principal by OIDC claim","value":{"fetch_by":{"type":"oidc","issuer":"https://my-auth-server.identity.api.konghq.com","claim":{"name":"sub","value":"my-subject"}}}},"fetchByConsumer":{"summary":"Fetch a principal by Kong consumer","value":{"fetch_by":{"type":"consumer","consumer_id":"c1f5b3e2-1234-4abc-8def-000000000001"}}},"fetchByCustom":{"summary":"Fetch a principal by custom key/value","value":{"fetch_by":{"type":"custom","key":"oidc:issuer:ki.com","value":"my-service"}}},"fetchByPrincipalID":{"summary":"Fetch a principal by principal ID","value":{"fetch_by":{"type":"principal_id","principal_id":"c1f5b3e2-1234-4abc-8def-000000000006"}}}}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/octet-stream":{"schema":{"description":"Binary Cap'n Proto encoded error response.\nSchema definition: https://github.com/kong-konnect/sliver/blob/main/capnp/errorresponse.capnp\n","type":"string","format":"binary"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"},"examples":{"UnauthorizedExample":{"$ref":"#/components/examples/UnauthorizedExample"}}}}},"BadRequest":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"}}}},"Forbidden":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"},"examples":{"UnauthorizedExample":{"$ref":"#/components/examples/ForbiddenExample"}}}}},"NotFound":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/NotFoundError"},"examples":{"NotFoundExample":{"$ref":"#/components/examples/NotFoundExample"}}}}}}}}
```
