PermuteDocs
Go to Permute

Identity and access

Permissions and sharing

Understand who can access resources, share data and apps, and grant or revoke permissions.

Signing in establishes who you are. Permissions determine which resources you can use and what you can do with them. Users, apps, and API keys have their own access; creating an app or key does not give it your permissions.

Permissions, grants, and scope

Suppose you give Maya Read access to a Sales dataset until Friday. The grant assigns that permission to Maya, its scope covers the Sales dataset, and its expiry ends that grant on Friday.

TermMeaning
PrincipalThe identity acting on a resource, such as a user, app, or API key.
ResourceA dataset, connector, app, Business Action, or another item with access controls.
PermissionAuthority to perform an operation, such as reading a dataset or publishing an app.
GrantAn assignment of permissions to a user, app, API key, or organization/workspace audience.
ScopeThe resources and organization or workspace boundary that access covers.
RoleAn organization or workspace membership role, such as administrator, member, or guest.

In the permissions API, principalType and principalId identify the recipient of a grant. An organization or workspace recipient lets eligible members receive access through membership.

Membership and resource access

Organization and workspace roles govern membership and administration. Resource access can come from ownership, a direct grant, or grants shared with eligible organization or workspace members. Guests have restricted membership inheritance. Joining a workspace or signing in through SSO does not establish access to every resource in it.

Use sharing settings or client.permissions.inspect to review current resource access. Removing one grant may leave access through ownership or another grant, so check the resulting access when revoking permissions.

Access levels and named permissions

Level-based grants use read, write, and admin. Admin includes Write and Read; Write includes Read. The operations each level permits depend on the resource.

Apps and Business Actions also support named permissions, such as View details, Edit draft, Publish, Run, and Change access. Sharing presets group these permissions for common tasks. Review the included operations when choosing a preset: editing or publishing a Business Action does not grant permission to run it.

Workspaces also have the named permission Change AI limits (workspace.manage_ai_credits), which workspace admin access includes. It lets a person or API key change the monthly AI credit limits of the workspace's Business Actions and operations which they can view. To grant it alone, choose the Can change AI limits preset on the workspace, or grant level: 'admin' with operations: ['workspace.read', 'workspace.manage_ai_credits']. Also grant view access to the Business Actions and operations, for example Can view on All Business Actions and All Data Operations.

See action permissions for authoring, publication, and source approval requirements.

Users, apps, and API keys

Access pathWhat must be allowed
UserCurrent resource access through ownership, direct sharing, or eligible membership.
API keyGrants assigned to that key, within its organization or workspace boundary.
App querySource Read permission for both the signed-in viewer and the app, plus access to the app.
App actionInvocation permission for both the viewer and app, with the action bound to the published app release.

For example, a viewer who can read Sales still cannot query it through an app without an app grant. Giving the app that grant also does not give every app viewer access to Sales. Follow the app permission matrix to configure both.

Business Actions run within their approved execution scope. Permission to run an action can allow bounded work without giving the caller direct access to its database or connectors. Keep source approval and invocation access separate; see Business Actions.

Caller access and automation access

Work can run on behalf of a caller or as approved automation. Running in a queue or on a schedule does not, by itself, grant access.

Execution modeAuthorityExample
Caller accessWorks on behalf of the initiating caller, within their resource permissions and connection limits.An answer job started through the SDK or MCP.
Automation accessUses authority approved for the automation and can continue after its configurator signs out.A scheduled Business Action running within its published capabilities.

The execution identity is the principal acting during a run; approved access limits what it may do. A trigger starts work and a run records an execution (neither creates resource access). Permission to edit or control a saved action or workflow is separate from its execution authority and permission to read its results.

For example, an administrator can approve a Business Action that updates support tickets. A support rep can receive permission to run that bounded action without access to its underlying database. An authorized administrator can also schedule it; signing out does not pause that schedule. Follow the schedule guide for approval requirements and pause controls.

Grant and revoke access

Use Permute sharing or an authorized management client to grant access. Select the recipient, resource, and required permissions, then set an expiry if needed. Grants can cover one whole resource or all resources of a type. Review the full contents before sharing a source (including tables used by other apps).

The SDK exposes client.permissions.list, create, update, delete, and inspect; apps also have dedicated grant APIs. These calls require the management client’s own resource and delegation authority. Hosted app, delegated action, MCP, and connector sessions cannot manage grants. See the API reference for request fields and requirements.

Share a narrower view

Source query APIs currently require whole-resource access. Table, row, and column grants within a shared database, dataset, connector, or operation output do not authorize those reads. Filters in browser code cannot restrict what a viewer is authorized to retrieve.

For narrower access, share separately filtered Data Flow outputs while keeping broader sources restricted. For caller-specific current-state reads, use an approved Business Action. Follow the filtered-output guide to review refresh and historical access before sharing.

Approved connection access

CLI and MCP approvals limit what a connection can use within your current permissions. Approving a resource does not grant you access to it, and revoking your permission blocks further use through that connection. Review approvals in Sessions and connections.

Troubleshoot access

Check the selected workspace, the caller’s current permission, and any required app grant. A successful test as an administrator does not prove that intended viewers have access. Test as those viewers, including after revocation.

SDK errors can include permission_denied details on PermuteApiError.details. The reason can identify a missing caller permission, app grant, source approval, or declared action capability. Details are returned only when access checks permit disclosure; missing and unreadable resources can both return 404. A valid key or login does not bypass these checks.