> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant StackOne
    participant Provider

    Agent->>StackOne: POST /unified/check_permissions<br/>{ user_id, resource_id, action: "read" }
    StackOne->>Provider: Fetch user permissions for resource
    Provider-->>StackOne: Native role/permission data
    StackOne-->>Agent: { user.permissions: ["read"], allowed: true }
```

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](/iam/api-reference/resource-users/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](/iam/api-reference/roles/list-roles), and permissions granted via [group membership](/iam/api-reference/groups/list-groups). 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](/permissions-check/api-reference/check-permissions) with standard StackOne auth headers
* **StackOne CLI** — `stackone actions rpc unified_check_permissions` ([CLI reference](/guides/connector-engine/cli-reference))
* **Actions RPC** — [POST /actions/rpc](/platform/api-reference/actions/make-an-rpc-call-to-an-action) with `actionId: "unified_check_permissions"`