> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandfetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Viewer API

> Returns the identity of the credential used to authenticate the request — an API key or a user session token (JWT). Use it to verify a credential during integration setup (a `200` response means the credential is valid; `401`/`403` means it is missing, unknown, or revoked) and to display which API key and organization are connected. Requests to this endpoint are free: they never consume API credits.

<Note>
  Calling this endpoint is **free** — it never consumes API credits, so you
  can use it to verify a credential during integration setup or on a health
  check. API key responses include the key's current credit `usage`, matching
  the `x-api-key-quota` and `x-api-key-approximate-usage` headers returned by
  billable endpoints.
</Note>


## OpenAPI

````yaml GET /v2/viewer
openapi: 3.0.1
info:
  title: Brandfetch API
  description: >-
    Our APIs help you personalize your customer journey through unique branded
    experiences.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.brandfetch.io
security: []
paths:
  /v2/viewer:
    get:
      tags:
        - viewer
      summary: Get the authenticated viewer
      description: >-
        Returns the identity of the credential used to authenticate the request
        — an API key or a user session token (JWT). Use it to verify a
        credential during integration setup (a `200` response means the
        credential is valid; `401`/`403` means it is missing, unknown, or
        revoked) and to display which API key and organization are connected.
        Requests to this endpoint are free: they never consume API credits.
      operationId: getViewer
      responses:
        '200':
          description: >-
            The presented credential is valid. The `type` property indicates
            which kind of credential authenticated the request and determines
            the response shape.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ViewerApiKeyResponse'
                  - $ref: '#/components/schemas/ViewerUserResponse'
                discriminator:
                  propertyName: type
                  mapping:
                    api-key:
                      $ref: '#/components/schemas/ViewerApiKeyResponse'
                    user:
                      $ref: '#/components/schemas/ViewerUserResponse'
              examples:
                apiKey:
                  summary: Authenticated with an API key
                  value:
                    type: api-key
                    id: id5ZQvmz9A
                    urn: >-
                      urn:brandfetch:organization:cl5s9fps1275071ol9h7gs072m:api-key:id5ZQvmz9A
                    name: Production key
                    createdAt: '2026-05-12T09:14:07.000Z'
                    usage:
                      used: 1234
                      quota: 250000
                    organization:
                      id: cl5s9fps1275071ol9h7gs072m
                      urn: urn:brandfetch:organization:cl5s9fps1275071ol9h7gs072m
                      name: Acme Inc.
                user:
                  summary: Authenticated with a user session token
                  value:
                    type: user
                    id: cl2xkl6h90007w135197r5abc
                    urn: urn:brandfetch:user:cl2xkl6h90007w135197r5abc
                    name: Jane Doe
                    email: jane@acme.com
                    createdAt: '2025-11-02T16:41:12.000Z'
        '401':
          description: >-
            Unauthorized — the Authorization header is missing or the credential
            could not be resolved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    enum:
                      - Unauthorized
        '403':
          description: >-
            Forbidden — the credential was rejected, e.g. a revoked API key or
            an expired session token.
      security:
        - bearerAuth: []
components:
  schemas:
    ViewerApiKeyResponse:
      type: object
      title: API key
      description: The authenticated API key.
      required:
        - type
        - id
        - urn
        - name
        - createdAt
        - usage
        - organization
      properties:
        type:
          type: string
          enum:
            - api-key
          description: The kind of credential that authenticated the request.
        id:
          type: string
          description: Id of the API key.
        urn:
          type: string
          description: >-
            URN of the API key, e.g.
            `urn:brandfetch:organization:{organization.id}:api-key:{id}`.
        name:
          type: string
          nullable: true
          description: Display name of the API key, as set in the dashboard.
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: When the API key was created.
        usage:
          type: object
          description: >-
            API credit consumption for the current billing period, mirroring the
            `x-api-key-quota` and `x-api-key-approximate-usage` response headers
            of billable endpoints. Because this endpoint is free, `used` is the
            exact count — it is not approximated one ahead like the header.
          required:
            - used
            - quota
          properties:
            used:
              type: integer
              description: API credits consumed so far in the current billing period.
            quota:
              type: integer
              description: API credit allowance for the current billing period.
        organization:
          type: object
          description: The organization the API key belongs to.
          required:
            - id
            - urn
            - name
          properties:
            id:
              type: string
              description: Id of the organization.
            urn:
              type: string
              description: >-
                URN of the organization, e.g.
                `urn:brandfetch:organization:{id}`.
            name:
              type: string
              nullable: true
              description: Display name of the organization.
    ViewerUserResponse:
      type: object
      title: User
      description: The authenticated user (dashboard session token).
      required:
        - type
        - id
        - urn
        - name
        - email
        - createdAt
      properties:
        type:
          type: string
          enum:
            - user
          description: The kind of credential that authenticated the request.
        id:
          type: string
          description: Id of the user.
        urn:
          type: string
          description: URN of the user, e.g. `urn:brandfetch:user:{id}`.
        name:
          type: string
          nullable: true
          description: Full name of the user.
        email:
          type: string
          nullable: true
          description: Email address of the user.
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: When the user account was created.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````