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

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-kong-identity-auth-api-dev-0/versions/95ca6cb9-c471-4475-a351-61326ecea57b.md

# FetchPrincipalRequestPayload

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

## OpenAPI definition

```yaml
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
components:
  schemas:
    FetchBy:
      description: >
        The identity used to look up a principal. The `type` field determines
        the identity kind and the required fields.
      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
    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
    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
    FetchPrincipalRequestPayload:
      description: |
        The request payload used to look up a principal by a specific identity.
      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.
          type: boolean
        workspace_id:
          description: >
            Scopes the consumer lookup to a specific workspace within the
            control plane. Applicable only when include_consumer is true.
          type: string
      required:
        - fetch_by
```
