A permission lookup API that returns all subjects who can reach a specific resource and permission. It works in reverse from a resource to the people, tokens, or other subjects that have access, and it resolves inherited paths through groups or linked objects automatically.
How LookupSubjects works
LookupSubjects is a reverse permission query: you start with a resource and permission, then ask which subjects can reach it. That makes it especially useful when access is inherited through groups, nested relationships, or linked objects, because the API resolves those paths for you instead of forcing manual graph traversal.
The practical value is that it turns access review into a question about effective permissions rather than isolated grants. In large environments, that distinction matters because the real exposure is often not the direct assignment, but the full chain that leads to access.
Because the query is resource-centric, it also helps answer a common governance question: “who can do this?” rather than “what can this principal do?” That makes it a good fit for entitlement inspection, audit support, and blast-radius analysis.
Why it matters for access review
LookupSubjects is useful whenever direct assignments do not tell the whole story. A user, token, or service may gain access through multiple layers of inheritance, and a reverse lookup exposes the final effective set of subjects without requiring you to reconstruct each path by hand.
That is especially important when the same permission can be reached through different routes, such as group membership, linked objects, or higher-level role grants. If those paths are not resolved consistently, reviewers can miss real access or overestimate how restricted a resource actually is.
For teams working with non-human identities, this kind of reverse query is often the quickest way to see whether a resource is reachable by more subjects than expected. NHIMG’s Ultimate Guide to NHIs notes that only 5.7% of organisations have full visibility into their service accounts, which is why effective reachability analysis matters so much in practice.
Where it sits in an identity and authorization model
LookupSubjects is not an authentication feature, it is an authorization visibility feature. It answers a question about effective access after identity and policy decisions have already been made, which means it complements, rather than replaces, role design, entitlement review, and access governance.
The API is most useful when the underlying permission model is complex enough that a simple list of direct grants is misleading. In that setting, the output becomes a source of truth for access analysis because it captures inherited and indirect reachability in a single result set.
It also helps separate the subject from the mechanism. The subject might be a person, token, application, or other actor, but the important point is whether that actor can reach the target resource through the current authorization graph.
Common implementation and interpretation issues
LookupSubjects results can be misread if teams assume the output is only about direct assignment. In reality, the most valuable part of the lookup is often the inherited path, because that is where hidden access tends to accumulate and where reviews tend to miss the true scope of exposure.
Another common issue is treating the returned list as static. Access can change as groups, linked objects, and parent relationships change, so the result should be understood as a point-in-time view of effective reachability, not a permanent property of the resource.
When the result set is large, that is usually a signal to inspect the structure of access rather than the individual subjects first. Large reachability sets often indicate overbroad inheritance, poorly bounded group design, or excessive sharing patterns that deserve follow-up.
Risk and Threat Considerations
Reverse permission lookup exposes where access is broader than expected, which makes it valuable for finding excessive privilege, unintended inheritance, and attack paths that would otherwise remain hidden. The same visibility also helps defenders understand how a compromised subject could reach a sensitive resource through indirect grants.
Failure mechanism: Over-permissive group structures, linked-object inheritance, or stale entitlements can silently expand the set of subjects that can reach a resource. If those paths are not reviewed, a compromise of any member subject can become unauthorized access to the protected target.
Impact: The result can be data exposure, privilege abuse, or lateral movement through authorization paths that look narrower than they really are. In practice, that increases the chance that access review, incident response, and blast-radius assessments miss the true scope of risk.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST CSF 2.0 and CIS Controls v8 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST CSF 2.0 | GV.OC-01 — Organizational Context | Reverse access visibility supports understanding which subjects can reach critical resources. |
| PR.AA-01 — Identity and Access Management | LookupSubjects exposes effective authorization paths and inherited access relationships. | |
| PR.AA-02 — Identity Management, Authentication and Access Provisioning | The lookup surfaces inherited access that should be governed through provisioning and review. | |
| Recommendation — Use access-reachability results to inform governance decisions for sensitive resources. Review effective access paths to validate who can reach each resource. Reconcile inherited entitlements against intended access during provisioning and review. | ||
| CIS Controls v8 | 6.3 — Remove Dormant Access Rights | Reverse lookup helps find subjects that still retain effective access to a resource. |
| 6.5 — Privileged Account Management | Resource-to-subject lookup helps locate privileged reachability hidden behind groups or links. | |
| 6.7 — Review User Access Rights | The API directly supports periodic review of who can access a specific resource. | |
| Recommendation — Use effective-access queries to identify and remove unnecessary access rights. Validate privileged reachability through inherited paths before approving access. Run resource-centric access reviews to confirm the intended subject set. | ||
| OWASP Non-Human Identity Top 10 | NHI-02 — Secrets and Credential Management | The term covers who can reach resources via tokens and other subjects in NHI contexts. |
| NHI-03 — Privilege and Permissions Management | LookupSubjects reveals effective privilege created by inherited or linked authorization paths. | |
| NHI-10 — Visibility and Monitoring | Reverse lookup improves visibility into effective access across subjects and linked objects. | |
| Recommendation — Map token-backed access to the resource and verify only intended subjects can reach it. Check inherited permission paths to prevent unintended overprivilege. Use reverse access queries to improve visibility into effective reachability. | ||
Practitioner Guidance
What to watch for: Use LookupSubjects when you need to validate effective access, not just assigned access. If the result set is unexpectedly large, or if a sensitive resource has many inherited paths, treat that as a signal to review the authorization model rather than the individual subjects alone.
Governance implication: This is a strong fit for periodic access review, privileged resource review, and investigations that need a defensible answer to “who can reach this?” A clean lookup result is only useful if someone owns the follow-up when the answer is larger than expected.
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 19, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
