Query Oso Cloud

Use queries to determine which users have specific permissions, which resources a user can access, or to debug authorization issues.

Query Structure

A query has two parts:

1. Predicate: the rule name from your policy (e.g., has_permission).
2. Constraints: values to match, or wildcards (_).

Oso Cloud only evaluates rules that have the same number of parameters as your constraints.

Constraint Types

Type	Format	Example	Description
Exact value	Type:value	User:alice	Match this value exactly
Type wildcard	Type:_	User:_	Match any value of this type
Universal wildcard	_	_	Match any value of any type

Default types in CLI

When you omit the type in CLI queries, Oso Cloud assumes String:

• view becomes String:view
• admin becomes String:admin

Important: Type constraints match exactly. Subclasses don’t match parent types, even with Polar’s extends feature.

Common Query Patterns

Example policy:

actor User {}
resource Organization {}

has_permission(user: User, "view", org: Organization) if
  has_role(user, "member", org);

Check if a user has permission

oso-cloud query has_permission User:alice String:view Organization:acme

Returns a matching fact or (no results).

Find all users with a permission

oso-cloud query has_permission User:_ String:view Organization:acme

Use User:_ to match any user. Returns all users who can view the organization.

List a user's permissions

oso-cloud query has_permission User:alice String:_ Organization:acme

Returns all permissions the user has on the organization.

Find all resources a user can access

oso-cloud query has_permission User:alice view _

The wildcard _ matches any resource type, not just organizations.

Global rules

Global rules apply across the system and are not tied to specific resources.

# Find global admins
oso-cloud query has_role User:_ admin

# Check global permission
oso-cloud query has_permission User:alice edit

How Query Results Work

Oso Cloud returns facts that satisfy your query constraints. Facts come from:

• Literal facts – Defined directly in policies or added via the API.
• Inferred facts – Derived by evaluating policies. For example, this query:

oso-cloud query has_permission User:alice String:view Organization:acme

Makes Oso Cloud check if this policy rule applies:

has_permission(user: User, "view", org: Organization) if
  has_role(user, "member", org);

Oso Cloud binds alice to user and acme to org, then searches for:

has_role(User:alice, "member", Organization:acme)

If this fact exists, Oso Cloud returns:

has_permission User:alice view Organization:acme

This demonstrates role-based access control (RBAC) - permissions granted through role membership.

Queries vs Other APIs

Queries form the basis for all Oso Cloud APIs:

• authorize queries the allow predicate with your parameters.
• list queries with wildcards to find accessible resources.
• bulk-authorize runs multiple authorization queries.

Use direct queries for debugging, bulk operations, and custom checks.

Environment Scope

Each query runs against a single environment containing:

• Your Polar policies (authorization logic)
• Your facts (users, roles, and relationships)

Cross-environment queries are not supported.

Troubleshooting

No results returned?

• Check that your facts exist with oso-cloud facts list
• Verify policy syntax with oso-cloud policy validate
• Use wildcards to broaden your search

Unexpected results?

• Test individual policy rules in isolation
• Check fact relationships with targeted role/permission queries
• Use the policy editor’s test feature

---

Need help with queries? Schedule time with an Oso engineer - we’re happy to help.