Query API

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_PATH`
Returns	Entities (users, resources, groups)	Principal → entitlement access 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_PATH 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_PATH 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.
`entityTag`	object	Match by tag key/value. See Tag 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.

Tag match

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

key is required. value is optional — omit to match any value for that key. connectionId is optional — set it to restrict to tags sourced from a specific connection.

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_PATH 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_PATH queries

An ACCESS_PATH query returns paginated access paths — each result is one principal → entitlement pair, the terminal access level, the depth, and the chain of entity IDs in between.

Request

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

Field	Type	Description
`type`	string	Must be `ACCESS_PATH`.
`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`.
`includeCount`	boolean	When `true`, populate `totalCount` in the response. Omit on subsequent pages — recomputing is expensive.

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_PATH",
  "edges": [
    {
      "node": {
        "principalId": "0340f67b-6fcd-4559-8e56-9800735ba5e0",
        "entitlementId": "25b7382c-e144-42ba-a551-ad127c73d05b",
        "accessLevelName": "admin",
        "accessLevelRemoteId": "arn:aws:iam::123456789012:role/admin",
        "expiration": null,
        "depth": 2,
        "path": [
          "0340f67b-6fcd-4559-8e56-9800735ba5e0",
          "568f9489-d729-417a-85d3-bc70dff44f62",
          "25b7382c-e144-42ba-a551-ad127c73d05b"
        ]
      },
      "cursor": "b3BhcXVlLWN1cnNvci0x"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "b3BhcXVlLWN1cnNvci0x",
    "hasPreviousPage": false,
    "startCursor": ""
  },
  "totalCount": 6440
}

depth — number of hops from principal to entitlement (1 = direct).
path — entity IDs along the chain from principal to entitlement.
totalCount — exact count of matching paths; only populated when includeCount: true was set on the request.

Examples

All access paths for a specific user

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

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_PATH",
  "query": {
    "principalFilter": { "entityTypes": ["USER"] },
    "entitlementFilter": {
      "entityName": { "stringMatchType": "CONTAINS", "string": "billing-prod" }
    },
    "principalAccessFilters": {
      "hasAccessTo": {
        "entityName": { "stringMatchType": "CONTAINS", "string": "AdministratorAccess" }
      }
    }
  },
  "includeCount": true
}

Deprovisioning gap — direct access still held by suspended users Combines hrIdpStatus on the principal side with directOnly on the edge.

{
  "type": "ACCESS_PATH",
  "query": {
    "principalFilter": {
      "entityTypes": ["USER"],
      "hrIdpStatus": { "statuses": ["SUSPENDED", "DEPROVISIONED"] }
    },
    "entitlementFilter": { "entityTypes": ["RESOURCE", "GROUP"] },
    "edgeFilter": { "directOnly": true }
  },
  "includeCount": 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"
}

For ACCESS_PATH queries, omit includeCount on pages after the first — the total count is stable and recomputing it on every page is expensive.

Welcome

End user

Getting Started

Access Management

OpalScript

Paladin

OpalQuery

Auditing and Security

Custom Integrations

For Developers

Requirements

Endpoint

Query types

Entity filters

Name match

Tag match

IDP status match

Admin owner match

Logical composition

Relationship filters

NODE queries

Request

Response

Examples

ACCESS_PATH queries

Request

Edge filter

Advanced access filters

Response

Examples

​Requirements

​Endpoint

​Query types

​Entity filters

​Name match

​Tag match

​IDP status match

​Admin owner match

​Logical composition

​Relationship filters

​NODE queries

​Request

​Response

​Examples

​ACCESS_PATH queries

​Request

​Edge filter

​Advanced access filters

​Response

​Examples

​Pagination

Requirements

Endpoint

Query types

Entity filters

Name match

Tag match

IDP status match

Admin owner match

Logical composition

Relationship filters

NODE queries

Request

Response

Examples

ACCESS_PATH queries

Request

Edge filter

Advanced access filters

Response

Examples

Pagination