Opal Security opal-queries API

openapi: 3.2.0
info:
  contact:
    email: hello@opal.dev
    name: Opal Team
    url: https://www.opal.dev/
  description: The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically.
  title: Opal access-rules Opal Queries API
  version: '1.0'
servers:
- description: Production
  url: https://api.opal.dev/v1
tags:
- name: opal-queries
  description: Operations related to OpalQuery
paths:
  /queries/run:
    post:
      summary: Run an ad-hoc OpalQuery
      description: Runs an ad-hoc OpalQuery and returns the results. Currently supports NODE queries (users, resources, groups). This endpoint is only available to our OpalQuery beta group. Please contact Opal support if you'd like to be added to the beta.
      operationId: runOpalQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunOpalQueryRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpalQueryResults'
          description: The results of the OpalQuery.
      security:
      - BearerAuth: []
      tags:
      - opal-queries
components:
  schemas:
    PageInfo:
      type: object
      required:
      - hasNextPage
      - endCursor
      - hasPreviousPage
      - startCursor
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more items after the end cursor
        endCursor:
          type: string
          description: The cursor to continue pagination forwards
        hasPreviousPage:
          type: boolean
          description: Whether there are more items before the start cursor
        startCursor:
          type: string
          description: The cursor to continue pagination backwards
    OpalNodeQueryResults:
      type: object
      required:
      - type
      - edges
      - pageInfo
      description: Paginated results of a NODE-type OpalQuery — one edge per matched entity (user, resource, or group).
      properties:
        type:
          type: string
          enum:
          - NODE
        edges:
          type: array
          description: List of matched entities.
          items:
            $ref: '#/components/schemas/OpalQueryResultEdge'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    OpalQueryResultNode:
      type: object
      required:
      - id
      - name
      - entityType
      - entityItemType
      description: A matched entity from an OpalQuery result.
      properties:
        id:
          type: string
          format: uuid
          description: The entity's unique identifier.
        name:
          type: string
          description: The display name of the entity.
        entityType:
          type: string
          enum:
          - USER
          - GROUP
          - RESOURCE
          description: The top-level entity type.
        entityItemType:
          $ref: '#/components/schemas/EntityItemTypeEnum'
    StringMatchType:
      type: string
      description: How to match a string value against entity names.
      enum:
      - CONTAINS
      - EQUALS
      - STARTS_WITH
      - ENDS_WITH
    EntityTagFilter:
      type: object
      required:
      - key
      description: Filters entities by a tag key/value pair, optionally scoped to a connection.
      properties:
        key:
          type: string
          description: The tag key to filter by.
          example: team
        value:
          type: string
          description: The tag value to filter by. If omitted, matches any value for the given key.
          example: platform
        connectionId:
          type: string
          format: uuid
          description: If specified, filters by tags associated with this connection.
    EntityItemTypeEnum:
      description: Granular subtype of an entity.
      enum:
      - USER
      - SERVICE_USER
      - ACTIVE_DIRECTORY_GROUP
      - AWS_SSO_GROUP
      - DUO_GROUP
      - GIT_HUB_TEAM
      - GIT_LAB_GROUP
      - GOOGLE_GROUPS_GROUP
      - GOOGLE_GROUPS_GKE_GROUP
      - LDAP_GROUP
      - OKTA_GROUP
      - OKTA_GROUP_RULE
      - TAILSCALE_GROUP
      - TWINGATE_GROUP
      - TWINGATE_GROUP_SYNCED
      - OPAL_GROUP
      - OPAL_ACCESS_RULE
      - AZURE_AD_SECURITY_GROUP
      - AZURE_AD_MICROSOFT_365_GROUP
      - CONNECTOR_GROUP
      - SNOWFLAKE_ROLE
      - WORKDAY_USER_SECURITY_GROUP
      - DATABRICKS_ACCOUNT_GROUP
      - AWS_IAM_ROLE
      - AWS_EC2_INSTANCE
      - AWS_EKS_CLUSTER
      - AWS_RDS_POSTGRES_INSTANCE
      - AWS_RDS_POSTGRES_CLUSTER
      - AWS_RDS_MYSQL_INSTANCE
      - AWS_RDS_MYSQL_CLUSTER
      - AWS_ACCOUNT
      - AWS_SSO_PERMISSION_SET
      - AZURE_MANAGEMENT_GROUP
      - AZURE_RESOURCE_GROUP
      - AZURE_SUBSCRIPTION
      - AZURE_VIRTUAL_MACHINE
      - AZURE_STORAGE_ACCOUNT
      - AZURE_STORAGE_CONTAINER
      - AZURE_SQL_SERVER
      - AZURE_SQL_MANAGED_INSTANCE
      - AZURE_SQL_DATABASE
      - AZURE_SQL_MANAGED_DATABASE
      - AZURE_USER_ASSIGNED_MANAGED_Identity
      - AZURE_ENTRA_ID_ROLE
      - AZURE_ENTERPRISE_APP
      - CUSTOM
      - CUSTOM_CONNECTOR
      - GCP_ORGANIZATION
      - GCP_BUCKET
      - GCP_COMPUTE_INSTANCE
      - GCP_BIG_QUERY_DATASET
      - GCP_BIG_QUERY_TABLE
      - GCP_FOLDER
      - GCP_GKE_CLUSTER
      - GCP_PROJECT
      - GCP_CLOUD_SQL_POSTGRES_INSTANCE
      - GCP_CLOUD_SQL_MYSQL_INSTANCE
      - GCP_SERVICE_ACCOUNT
      - GIT_HUB_REPO
      - GIT_HUB_ORG_ROLE
      - GIT_LAB_PROJECT
      - GOOGLE_WORKSPACE_ROLE
      - MONGO_INSTANCE
      - MONGO_ATLAS_INSTANCE
      - OKTA_APP
      - OKTA_ROLE
      - OPAL_ROLE
      - OPAL_SCOPED_ROLE
      - PAGERDUTY_ROLE
      - TAILSCALE_SSH
      - TWINGATE_RESOURCE
      - SALESFORCE_PERMISSION_SET
      - SALESFORCE_PROFILE
      - SALESFORCE_ROLE
      - SNOWFLAKE_DATABASE
      - SNOWFLAKE_SCHEMA
      - SNOWFLAKE_TABLE
      - WORKDAY_ROLE
      - MYSQL_INSTANCE
      - MARIADB_INSTANCE
      - POSTGRES_INSTANCE
      - TELEPORT_ROLE
      - DATABRICKS_ACCOUNT_SERVICE_PRINCIPAL
      - ILEVEL_ADVANCED_ROLE
      example: OPAL_ROLE
      type: string
    OpalNodeQuery:
      type: object
      required:
      - type
      description: Request body for a NODE-type OpalQuery. Returns entities (users, resources, groups) matching the given filters.
      example:
        type: NODE
        query:
          nodeFilters:
            entityTypes:
            - RESOURCE
            entityTag:
              key: env
              value: prod
          accessFilters:
            isAccessibleBy:
              entityTypes:
              - USER
              entityTag:
                key: contractor
        first: 50
      properties:
        type:
          type: string
          enum:
          - NODE
        query:
          $ref: '#/components/schemas/OpalNodeQueryBody'
        first:
          type: integer
          description: Maximum number of results to return. Defaults to 200.
          example: 200
        after:
          type: string
          description: Cursor from a previous response to fetch the next page of results.
          example: 29827fb8-f2dd-4e80-9576-28e31e9934ac
    AccessRelationshipFilters:
      type: object
      description: 'Filters the returned nodes by the access edges connected to them. When `isAccessibleBy` and `hasAccessTo` are provided, the returned nodes must satisfy both edge constraints simultaneously.

        '
      properties:
        isAccessibleBy:
          description: Inbound-edge filter. The returned node must be accessible by at least one entity matching this filter.
          $ref: '#/components/schemas/AccessEntityFilters'
        hasAccessTo:
          description: Outbound-edge filter. The returned node must have access to at least one entity matching this filter.
          $ref: '#/components/schemas/AccessEntityFilters'
    RunOpalQueryRequest:
      description: Request body for running an ad-hoc OpalQuery. The `type` field determines which query schema applies.
      oneOf:
      - $ref: '#/components/schemas/OpalNodeQuery'
      discriminator:
        propertyName: type
        mapping:
          NODE: '#/components/schemas/OpalNodeQuery'
    OpalQueryResultEdge:
      type: object
      required:
      - node
      - cursor
      description: A single result edge from an OpalQuery, containing the matched entity and its pagination cursor.
      properties:
        node:
          $ref: '#/components/schemas/OpalQueryResultNode'
        cursor:
          type: string
          description: Opaque cursor for this entity, used for pagination.
    OpalQueryResults:
      description: Paginated results of an OpalQuery. The `type` field discriminates which result schema applies and mirrors the `type` field on the request.
      oneOf:
      - $ref: '#/components/schemas/OpalNodeQueryResults'
      discriminator:
        propertyName: type
        mapping:
          NODE: '#/components/schemas/OpalNodeQueryResults'
    EntityNameFilter:
      type: object
      required:
      - stringMatchType
      - string
      description: Filters entities by name using a string match strategy.
      properties:
        stringMatchType:
          $ref: '#/components/schemas/StringMatchType'
        string:
          type: string
          description: The string value to match against the entity name.
          example: engineering
    AccessEntityFilters:
      type: object
      description: Filters for matching entities by type, name, tag, IDs, connections, or access levels. Supports recursive logical composition via allOf/anyOf.
      properties:
        entityTypes:
          type: array
          description: Filter by entity type. Only RESOURCE, GROUP, and USER are queryable via OpalQuery.
          items:
            type: string
            enum:
            - RESOURCE
            - GROUP
            - USER
        entityItemTypes:
          type: array
          description: Filter by entity item types.
          items:
            $ref: '#/components/schemas/EntityItemTypeEnum'
        entityName:
          $ref: '#/components/schemas/EntityNameFilter'
        entityTag:
          $ref: '#/components/schemas/EntityTagFilter'
        entityIDs:
          type: array
          description: Filter by specific entity UUIDs.
          items:
            type: string
            format: uuid
        importedFromApp:
          type: array
          description: Filter by app IDs from which returned nodes will be imported from.
          items:
            type: string
            format: uuid
        roleRemoteIds:
          type: array
          description: Filter by role remote IDs. Can only be applied within a hasAccessTo clause.
          items:
            type: string
        roleNames:
          type: array
          description: Filter by role display names (e.g. "Admin", "Read"). Can only be applied within a hasAccessTo clause.
          items:
            type: string
        allOf:
          type: array
          description: "A list of nested filters that must all match (logical AND). Each\n item has the same shape as this object — scalar fields like\n `entityTypes` or `entityTag`, and can further nest `allOf`,\n `anyOf`, or `not`.\n"
          items:
            $ref: '#/components/schemas/AccessEntityFilters'
        anyOf:
          type: array
          description: "A list of nested filters where at least one must match (logical\n OR). Each item has the same shape as this object.\n"
          items:
            $ref: '#/components/schemas/AccessEntityFilters'
        not:
          description: 'Excludes entities matching the embedded filter (logical NOT). Pass a filter object with the same shape as this one — typically a single scalar field, like `{not: {entityTypes: ["RESOURCE"]}}` to exclude resources.

            '
          type: object
          x-go-type: AccessEntityFilters
    OpalNodeQueryBody:
      type: object
      description: The filter body for a NODE-type OpalQuery.
      properties:
        nodeFilters:
          $ref: '#/components/schemas/AccessEntityFilters'
        accessFilters:
          $ref: '#/components/schemas/AccessRelationshipFilters'
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http