Permissions Check

Check whether a specific user can access a specific resource and what permissions they hold — across all connected integration providers.

The Permissions Check service answers a single question: can this user access this resource?

Given a user identifier and a resource ID, it returns the permissions that user holds on that resource. If you also specify an action (read, write, comment, delete, export), it tells you whether that action is allowed.

Why it exists

AI agents using RAG retrieve content chunks from indexed organizational data. Each chunk traces back to a source resource. Before including a chunk in a response, the agent needs to verify: can this user actually see this?

Without a unified check, agents either skip permission verification (a security risk) or build bespoke logic per provider (costly and fragile). The Permissions Check service handles this with a single API call regardless of which provider the resource comes from.

Use cases

RAG chunk gating

Before including a retrieved content chunk in an agent response, call POST /unified/check_permissions with the chunk’s source resource ID and action: "read". Only include the chunk if allowed: true.

Pre-mutation guard

Before an agent performs a write operation on behalf of a user — commenting on a document, posting to a channel — verify the user holds the required permission first.

Permission summary

Omit the action field to get a full list of what the user can do on a resource, without checking a specific action.

Messaging channel membership check

Before sending a message or notification to a channel on behalf of a user, verify they are a member and hold the required permission.

How it works

The service resolves the user (by ID or email), fetches their permissions for the resource from the integration provider, maps provider-native roles to the unified permission types, and returns the result.

Relationship to IAM

The Permissions Check service complements the IAM List Resource Users endpoint:

	Permissions Check	List Resource Users
Question	Can this user do X on this resource?	Who has access to this resource?
Input	User + resource + optional action	Resource type + resource ID
Output	Single user’s permissions + yes/no	All users with access, roles expanded
Best for	Fast per-user gate checks	Full access audits

When resolving permissions, the service accounts for the full IAM graph — direct permissions on the user, permissions inherited through role assignments, and permissions granted via group membership. The returned user.permissions reflect the union of all of these.

Calling the service

The service is available via three interfaces:

• HTTP — POST /unified/check_permissions with standard StackOne auth headers
• StackOne CLI — stackone actions rpc unified_check_permissions (CLI reference)
• Actions RPC — POST /actions/rpc with actionId: "unified_check_permissions"