openapi: 3.2.0
info:
  title: Omni Who Am I API
  description: The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more.
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
  description: Production
  variables:
    instance:
      default: blobsrus
      description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
  description: Playground
  variables:
    instance:
      default: blobsrus
      description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: Whoami
  description: Inspect your own user permissions
paths:
  /v1/whoami:
    get:
      description: 'Returns the authenticated caller''s own identity, API key scope, organization role, and resolved per-model permissions.


        Self-scoped and available to non-admins: it lets a caller decide whether an action is permitted without attempting it. Pass `modelId` to scope `rolesByModel` to specific models.'
      operationId: whoami
      summary: Get current identity and permissions
      tags:
      - Whoami
      parameters:
      - name: modelId
        in: query
        schema:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        required: false
        description: 'Optional model filter. A single model ID or a comma-separated list.


          When provided, `rolesByModel` in the response will contain only these models. When omitted, models the caller can access are returned up to a limit; see `rolesByModelTruncated`.

          '
      responses:
        '200':
          description: Caller's identity, key scope, org role, and per-model permissions
          content:
            application/json:
              schema:
                type: object
                required:
                - keyScope
                - orgRole
                - rolesByModel
                - user
                properties:
                  keyScope:
                    type: string
                    enum:
                    - user
                    - organization
                    description: 'Scope of the API key in use.


                      - `user` - Personal Access Token. This is a user-scoped key (PAT/OAuth) that acts as a single user and cannot use SCIM, regardless of the user''s organization role.

                      - `organization` - Organization API key

                      '
                  orgRole:
                    type: string
                    enum:
                    - MEMBER
                    - ORG_ADMIN
                    description: The caller's organization role.
                    example: MEMBER
                  rolesByModel:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/WhoamiModelRole'
                    description: Resolved role and effective permissions per model, keyed by model ID. Connection role resolves per shared model, so this is per-model rather than a single global role.
                  rolesByModelTruncated:
                    type: boolean
                    description: Present and `true` when `rolesByModel` was truncated because the caller can access more models than the unfiltered limit. Pass a `modelId` filter to retrieve specific models.
                  user:
                    $ref: '#/components/schemas/WhoamiUser'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
        '404':
          description: One or more requested `modelId`s do not exist or are not accessible to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
components:
  schemas:
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
      - detail
      - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
      - detail
      - status
    WhoamiModelRole:
      type: object
      required:
      - baseRole
      - connectionId
      - permissions
      - roleName
      properties:
        baseRole:
          type: string
          description: The resolved base role. For custom roles, the base role they extend.
          example: QUERIER
        connectionId:
          type: string
          description: The connection this model belongs to
        permissions:
          type: array
          items:
            type: string
            enum:
            - QUERY_FULL_MODEL
            - QUERY_SQL
            - VIEW_SQL
            - QUERY_TOPICS
            - RUN_CONTENT_QUERIES
            - DOWNLOAD_CONTENT_QUERY
            - UPLOAD_CSV
            - SCHEDULE
            - SAVE_SPREADSHEETS
            - USE_AI
            - USE_WORKBOOKS
            - UPDATE
            - UPDATE_RESTRICTED
          description: "The caller''s resolved/effective permissions on this model, reflecting custom roles. This is a capability signal for the directly-roleable model kinds (schema / shared / extension). \n\nIt does not enumerate the permissions you derive on branch, workbook, and query models from your role on the base model they descend from - bsence here does not mean you lack access on those derived models.`MANAGE_MODEL`, `READ`, and `REFRESH_SCHEMA` are also not reported: they derive from connection / sibling-model roles rather than a per-model rule.\n"
          example:
          - QUERY_TOPICS
          - QUERY_SQL
          - USE_WORKBOOKS
        roleName:
          type: string
          description: The resolved role name; may be a custom role. Use `permissions` to decide capability.
          example: QUERIER
    WhoamiUser:
      type: object
      required:
      - id
      - membershipId
      properties:
        id:
          type: string
          description: The caller's user ID
        membershipId:
          type: string
          description: The caller's own membership ID within this organization. This is the ID accepted by the [Get model roles endpoint](/api/user-model-roles/retrieve-user-model-roles) and is distinct from the user ID.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#token-types).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`

        '
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

        '