> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve the caller identity

> **Disclaimer:** This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the identity of the authenticated caller. For a user (JWT or clickhousectl token) the result carries the user fields; for an organization API key it carries the key fields instead. Use `actorType` to tell the two apart.

<span data-endpoint-badge="Beta"><Badge color="blue">Beta</Badge></span>

**Disclaimer:** This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the identity of the authenticated caller. For a user (JWT or clickhousectl token) the result carries the user fields; for an organization API key it carries the key fields instead. Use `actorType` to tell the two apart.


## OpenAPI

````yaml _specs/cloud-openapi.json GET /v1/whoami
openapi: 3.1.1
info:
  title: OpenAPI spec for ClickHouse Cloud
  version: '1.0'
  contact:
    name: ClickHouse Support
    url: >-
      https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1194182
    email: support@clickhouse.com
servers:
  - url: https://api.clickhouse.cloud
security:
  - basicAuth: []
tags:
  - name: Organization
  - name: User management
  - name: Billing
  - name: Role Management
  - name: Service
  - name: Backup
  - name: Snapshot
  - name: API keys
  - name: Prometheus
  - name: ClickPipes
  - name: ClickStack
  - name: Postgres
  - name: UDF
  - name: Query API endpoints
  - name: Saved queries
paths:
  /v1/whoami:
    get:
      tags:
        - User management
      summary: Resolve the caller identity
      description: >-
        **Disclaimer:** This beta endpoint is evolving; the API contract may
        change. <br /><br /> Returns the identity of the authenticated caller.
        For a user (JWT or clickhousectl token) the result carries the user
        fields; for an organization API key it carries the key fields instead.
        Use `actorType` to tell the two apart.
      operationId: whoamiGet
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/Whoami'
        '400':
          description: >-
            The request cannot be processed due to a client error. Please verify
            your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: >-
            An internal server error has occurred. If this issue persists,
            please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
components:
  schemas:
    Whoami:
      oneOf:
        - $ref: '#/components/schemas/WhoamiUser'
        - $ref: '#/components/schemas/WhoamiApiKey'
    WhoamiUser:
      properties:
        actorType:
          description: >-
            Discriminator identifying the caller as a user (JWT or clickhousectl
            token).
          type: string
          const: user
        userId:
          description: Unique ID of the user.
          type: string
          format: uuid
        email:
          description: Email address of the user.
          type: string
          format: email
        name:
          description: Full name of the user.
          type: string
        organizations:
          type: array
          description: Organizations the user belongs to.
          items:
            $ref: '#/components/schemas/WhoamiOrganization'
      required:
        - actorType
        - userId
        - email
        - name
        - organizations
    WhoamiApiKey:
      properties:
        actorType:
          description: Discriminator identifying the caller as an organization API key.
          type: string
          const: apiKey
        keyId:
          description: Unique ID of the API key.
          type: string
        name:
          description: Name of the API key.
          type: string
        organizationId:
          description: ID of the organization that owns the API key.
          type: string
          format: uuid
      required:
        - actorType
        - keyId
        - name
        - organizationId
    WhoamiOrganization:
      properties:
        organizationId:
          description: ID of the organization the user belongs to.
          type: string
          format: uuid
        organizationName:
          description: Name of the organization.
          type: string
      required:
        - organizationId
        - organizationName
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use key ID and key secret obtained in ClickHouse Cloud console:
        https://clickhouse.com/docs/cloud/manage/openapi
      x-permission-scopes: >-
        The scope list of a `security` requirement holds ClickHouse Cloud API
        key permission ids (for example `control-plane:organization:view`), not
        OAuth scopes. OpenAPI has no field for API key permissions, so this is
        the closest available place. A key must hold every permission listed on
        an operation to call it; an operation with no scopes needs none beyond a
        valid key. Every operation declares at most one requirement object,
        always for this scheme, so the list is only ever conjunctive —
        alternative sets of permissions are never expressed.

````