Query API

Run ad-hoc OpalQuery requests over HTTP to find entities and traverse access relationships.

POST /queries/run is in beta and limited to organizations in the OpalQuery beta. Contact Opal support to be added.

The POST /queries/run endpoint is the programmatic equivalent of the OpalQuery builder — useful for scripted audits, reporting pipelines, and one-off investigations.

​

Requirements

See Requirements in the Overview. You’ll also need an Opal API token — see Authentication.

​

Endpoint

POST https://api.opal.dev/v1/queries/run
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

The full schema and an interactive playground are available under API Reference → Opal API in the navigation.

​

Query types

Every request sets type to one of two modes:

	NODE	ACCESS
Returns	Entities (users, resources, groups)	Principal → entitlement access grants and paths
Use when	You want a list of entities matching certain properties or access relationships	You want to see who has access to what, how, and through which chain
Required field	At least one of nodeFilters or accessFilters	At least one of principalFilter or entitlementFilter

Both modes use the same filter vocabulary — AccessEntityFilters to describe entities, and AccessRelationshipFilters to traverse access edges. The Entity filters and Relationship filters sections below document these shared building blocks; the NODE queries and ACCESS queries sections show how each mode uses them.

​

Entity filters

An AccessEntityFilters object describes a set of entities by their own properties. It is used in both modes: as nodeFilters / accessFilters.isAccessibleBy / accessFilters.hasAccessTo in NODE queries, and as principalFilter / entitlementFilter / the nested filters inside principalAccessFilters and entitlementAccessFilters in ACCESS queries.

All fields are optional. Multiple sibling fields are combined with AND.

Field	Type	Description
entityTypes	string[]	Top-level type: USER, RESOURCE, and/or GROUP.
entityItemTypes	enum[]	Granular subtype, e.g. AWS_IAM_ROLE, OKTA_GROUP, GIT_HUB_REPO. Full list in the OpenAPI spec (EntityItemTypeEnum).
entityName	object	Match by display name. See Name match.
entityDescription	object	Match resources and groups by description substring. See Description match.
entityTag	object	Match by tag key/value. See Tag match.
entityTagKey	object	Match entities with any tag having one of the given keys, regardless of value. See Tag key match.
hrIdpStatus	object	Match users by HR/IDP lifecycle status. See IDP status match.
entityAdminOwner	object	Match resources and groups by admin owner. See Admin owner match.
entityIDs	uuid[]	Restrict to specific entity UUIDs.
importedFromApp	uuid[]	Restrict to entities imported from one or more app (connection) IDs.
allOf	object[]	Nested filters — all must match (logical AND).
anyOf	object[]	Nested filters — at least one must match (logical OR).
not	object	Nested filter — exclude entities that match it (logical NOT).

​

Name match

{
  "entityName": {
    "stringMatchType": "CONTAINS",
    "string": "prod"
  }
}

stringMatchType is one of EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH.

​

Description match

{
  "entityDescription": {
    "string": "production",
    "not": false
  }
}

Matches resources and groups whose description contains string (case-insensitive substring match). User entities have no description and never match this filter in either polarity. Set not: true to return resources and groups whose description does not contain string (including entities with an empty description).

​

Tag match

{
  "entityTag": {
    "key": "env",
    "value": "prod",
    "connectionId": "9b1c33a4-..."
  }
}

key is required. value is optional — if omitted, matches only tags with no value (use entityTagKey to match any value for a key). connectionId is optional — set it to restrict to tags sourced from a specific connection.

​

Tag key match

{
  "entityTagKey": {
    "keys": ["Critical", "SOX"]
  }
}

Matches entities that have at least one tag whose key is in keys, regardless of the tag’s value (including tags with no value).

​

IDP status match

{
  "hrIdpStatus": {
    "statuses": ["SUSPENDED", "DEPROVISIONED"],
    "not": false
  }
}

Matches users by HR/IDP lifecycle status. statuses is one or more of ACTIVE, SUSPENDED, DEPROVISIONED, DELETED, NOT_FOUND, combined with OR. Groups and resources never match this filter, in either polarity. Set not: true to invert within the user domain (e.g. “users whose IDP status is NOT active”).

​

Admin owner match

{
  "entityAdminOwner": {
    "ownerIDs": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
    "not": false
  }
}

Matches resources and groups by admin owner. ownerIDs is a list of owner (group) UUIDs; an entity matches if its admin owner is any of them. User entities never match this filter, in either polarity. Set not: true to return resources/groups not owned by the given owners.

​

Logical composition

allOf, anyOf, and not each take the same shape as the outer filter and can be nested arbitrarily deep.

{
  "entityTypes": ["RESOURCE"],
  "allOf": [
    { "entityTag": { "key": "env", "value": "prod" } },
    { "entityTag": { "key": "team", "value": "platform" } }
  ],
  "not": { "entityItemTypes": ["AWS_IAM_ROLE"] }
}

Resources tagged env=prod and team=platform, excluding AWS IAM roles.

​

Relationship filters

An AccessRelationshipFilters object traverses access edges. It is used in both modes: as accessFilters in NODE queries to narrow returned entities by their access relationships, and as principalAccessFilters / entitlementAccessFilters in ACCESS queries to scope one side of the path by its own access edges.

Field	Direction	Question it answers
isAccessibleBy	Inbound edge	The target entity is accessible by ≥ 1 entity matching this filter.
hasAccessTo	Outbound edge	The target entity has access to ≥ 1 entity matching this filter.

Both fields take an AccessEntityFilters object. Both direct and indirect (through nested group memberships) edges are considered. When both are set, both must be satisfied.

hasAccessTo additionally accepts two fields that constrain the role on the access edge:

Field	Type	Description
roleNames	string[]	Match the role display name (e.g. write, Admin).
roleRemoteIds	string[]	Match the role remote ID on the access edge.

These are only honored inside hasAccessTo — they have no effect in isAccessibleBy or entity filters.

---

​

NODE queries

A NODE query returns a paginated list of entities (users, resources, or groups) that match your filters.

​

Request

{
  "type": "NODE",
  "query": {
    "nodeFilters": { },
    "accessFilters": {
      "isAccessibleBy": { },
      "hasAccessTo": { }
    }
  },
  "first": 200,
  "after": "<cursor>"
}

Field	Type	Description
type	string	Must be NODE.
query.nodeFilters	object	AccessEntityFilters — which entities to return.
query.accessFilters	object	AccessRelationshipFilters — further restrict by access edges (optional).
first	integer	Maximum results per page. Defaults to 200.
after	string	Cursor from a previous response’s pageInfo.endCursor.

At least one of nodeFilters or accessFilters is required.

​

Response

{
  "type": "NODE",
  "edges": [
    {
      "node": {
        "id": "8b0f6e0c-4b71-4f3b-9c61-1d1d5e6a51e4",
        "name": "prod-readonly",
        "entityType": "RESOURCE",
        "entityItemType": "AWS_IAM_ROLE"
      },
      "cursor": "b3BhcXVlLWN1cnNvci0x"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "b3BhcXVlLWN1cnNvci0x",
    "hasPreviousPage": false,
    "startCursor": "b3BhcXVlLWN1cnNvci0w"
  }
}

node.id is the entity’s Opal UUID — pass it to other API endpoints (e.g. GET /resources/{resource_id}) to fetch full details.

​

Examples

All users

{
  "type": "NODE",
  "query": {
    "nodeFilters": { "entityTypes": ["USER"] }
  }
}

AWS IAM roles tagged env=prod, accessible by contractors

Combines entityItemTypes, entityTag, and accessFilters.

{
  "type": "NODE",
  "query": {
    "nodeFilters": {
      "entityItemTypes": ["AWS_IAM_ROLE"],
      "entityTag": { "key": "env", "value": "prod" }
    },
    "accessFilters": {
      "isAccessibleBy": {
        "entityTypes": ["USER"],
        "entityTag": { "key": "contractor" }
      }
    }
  }
}

Users with write access to a specific GitHub repo

Uses roleRemoteIds inside hasAccessTo to filter by role.

{
  "type": "NODE",
  "query": {
    "nodeFilters": { "entityTypes": ["USER"] },
    "accessFilters": {
      "hasAccessTo": {
        "entityItemTypes": ["GIT_HUB_REPO"],
        "entityName": { "stringMatchType": "EQUALS", "string": "payments-service" },
        "roleRemoteIds": ["write"]
      }
    }
  }
}

Resources owned by a specific admin, accessible by suspended users (deprovisioning gap)

Combines entityAdminOwner and hrIdpStatus.

{
  "type": "NODE",
  "query": {
    "nodeFilters": {
      "entityTypes": ["RESOURCE"],
      "entityAdminOwner": {
        "ownerIDs": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
      }
    },
    "accessFilters": {
      "isAccessibleBy": {
        "entityTypes": ["USER"],
        "hrIdpStatus": { "statuses": ["SUSPENDED", "DEPROVISIONED"] }
      }
    }
  }
}

Full curl request

curl -X POST https://api.opal.dev/v1/queries/run \
  -H "Authorization: Bearer $OPAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "NODE",
    "query": {
      "nodeFilters": {
        "entityTypes": ["RESOURCE"],
        "entityTag": { "key": "env", "value": "prod" }
      },
      "accessFilters": {
        "isAccessibleBy": {
          "entityTypes": ["USER"],
          "entityTag": { "key": "contractor" }
        }
      }
    },
    "first": 100
  }'

---

​

ACCESS queries

An ACCESS query returns paginated access grants — each result represents one (principal, entitlement, access level) grant, along with whether it is direct, its effective expiration, and all intermediate paths connecting the principal to the entitlement.

​

Request

{
  "type": "ACCESS",
  "query": {
    "principalFilter": { },
    "entitlementFilter": { },
    "principalAccessFilters": {
      "hasAccessTo": { },
      "isAccessibleBy": { }
    },
    "entitlementAccessFilters": {
      "hasAccessTo": { },
      "isAccessibleBy": { }
    },
    "edgeFilter": {
      "directOnly": true,
      "accessDurationType": "EXPIRING_ONLY"
    },
    "accessLevelRemoteIds": ["..."],
    "accessLevelNames": ["..."]
  },
  "first": 200,
  "after": "<cursor>"
}

Field	Type	Description
type	string	Must be ACCESS.
query.principalFilter	object	AccessEntityFilters — which principals (path start) to consider.
query.entitlementFilter	object	AccessEntityFilters — which entitlements (path end) to consider.
query.principalAccessFilters	object	AccessRelationshipFilters — scope principals by their own access edges (optional). See Advanced access filters.
query.entitlementAccessFilters	object	AccessRelationshipFilters — scope entitlements by their own access edges (optional). See Advanced access filters.
query.edgeFilter	object	Constrain the terminal access edge. See Edge filter.
query.accessLevelRemoteIds	string[]	Restrict to paths whose terminal access level matches one of these remote IDs.
query.accessLevelNames	string[]	Restrict to paths whose terminal access level matches one of these display names.
first	integer	Maximum results per page. Defaults to 200.
after	string	Cursor from a previous response’s pageInfo.endCursor.

At least one of principalFilter or entitlementFilter is required.

​

Edge filter

{
  "edgeFilter": {
    "directOnly": true,
    "accessDurationType": "EXPIRING_ONLY"
  }
}

• directOnly — when true, return only direct (depth-1) principal → entitlement edges.
• accessDurationType — EXPIRING_ONLY or PERMANENT_ONLY, to constrain by whether the terminal access expires.

​

Advanced access filters

principalAccessFilters and entitlementAccessFilters scope one side of the path by its own access edges, using the same AccessRelationshipFilters shape as NODE accessFilters:

• principalAccessFilters.hasAccessTo — keep only principals that also have access to a matching entity.
• principalAccessFilters.isAccessibleBy — keep only principals that are also accessible by a matching entity.
• entitlementAccessFilters — the same, applied to the entitlement side.

Each access filter only takes effect when that side also carries an entity filter: principalAccessFilters requires principalFilter, and entitlementAccessFilters requires entitlementFilter. Supplied without a matching entity filter, it is silently ignored.

​

Response

{
  "type": "ACCESS",
  "edges": [
    {
      "node": {
        "principalId": "0340f67b-6fcd-4559-8e56-9800735ba5e0",
        "entitlementId": "25b7382c-e144-42ba-a551-ad127c73d05b",
        "accessLevelName": "admin",
        "accessLevelRemoteId": "arn:aws:iam::123456789012:role/admin",
        "effectiveExpiration": null,
        "isDirect": false,
        "paths": [
          {
            "path": [
              "0340f67b-6fcd-4559-8e56-9800735ba5e0",
              "568f9489-d729-417a-85d3-bc70dff44f62",
              "25b7382c-e144-42ba-a551-ad127c73d05b"
            ],
            "expiration": null
          }
        ]
      },
      "cursor": "b3BhcXVlLWN1cnNvci0x"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "b3BhcXVlLWN1cnNvci0x",
    "hasPreviousPage": false,
    "startCursor": ""
  }
}

• isDirect — true if any path in paths is a direct 2-node grant ([principalId, entitlementId]).
• effectiveExpiration — when this grant expires across all paths; null if at least one path is permanent.
• paths — all paths through which principalId holds this access level on entitlementId. Each entry includes the path array of entity IDs from principal to entitlement and that path’s expiration (null if permanent).

​

Examples

All access grants for a specific user

{
  "type": "ACCESS",
  "query": {
    "principalFilter": {
      "entityIDs": ["29827fb8-f2dd-4e80-9576-28e31e9934ac"]
    }
  }
}

Separation of duties — users who can reach billing-prod and also hold admin access

Uses principalAccessFilters.hasAccessTo to scope principals to those with an additional access relationship.

{
  "type": "ACCESS",
  "query": {
    "principalFilter": { "entityTypes": ["USER"] },
    "entitlementFilter": {
      "entityName": { "stringMatchType": "CONTAINS", "string": "billing-prod" }
    },
    "principalAccessFilters": {
      "hasAccessTo": {
        "entityName": { "stringMatchType": "CONTAINS", "string": "AdministratorAccess" }
      }
    }
  }
}

Deprovisioning gap — direct access still held by suspended users

Combines hrIdpStatus on the principal side with directOnly on the edge.

{
  "type": "ACCESS",
  "query": {
    "principalFilter": {
      "entityTypes": ["USER"],
      "hrIdpStatus": { "statuses": ["SUSPENDED", "DEPROVISIONED"] }
    },
    "entitlementFilter": { "entityTypes": ["RESOURCE", "GROUP"] },
    "edgeFilter": { "directOnly": true }
  }
}

---

​

Pagination

Both query types use cursor-based pagination. Set first to control the page size (default 200). When pageInfo.hasNextPage is true, pass pageInfo.endCursor as after on the next request.

{
  "type": "NODE",
  "query": { "nodeFilters": { "entityTypes": ["USER"] } },
  "first": 500,
  "after": "b3BhcXVlLWN1cnNvci0x"
}