Before you start
Workflow
- 1Use an existing app and discover the exact sources it needs. Choose direct source reads, filtered outputs, or an approved delegated action before granting access.
- 2Arrange access for both the app and intended viewers. The browser example below initializes app; the assistant-check snippet reuses that browser client.
- 3Test queries and the assistant as intended viewers and as viewers without access, including after revocation.
Choose how the app reads data
Use the governed source and query APIs for ordinary app reads. Discover permitted sources with app.sources.list(), inspect a selected source with app.sources.get(sourceId), then read counts, lists, filters, and aggregates with app.query(). Approve source read grants for the app and ensure each viewer has source read permission. These queries use the app session (no browser API key) and need no Business Action or source revision binding.
Use @permute/sdk@^0.13.0 or newer so app.query() polls long-running native queries and returns rows. Show a loading state while awaiting it; use app.startQuery() and app.getQuery() when the interface needs explicit progress. Existing app bundles that omit waitMs retain synchronous queries and their existing request timeout limits; no rebuild is required to keep using them. Aborting the client wait does not cancel warehouse execution.
Source discovery and queries currently require whole-resource read permission on both the viewer and app. This applies to managed databases, datasets, synced connectors, and operation outputs such as Data Flow outputs. A table selection limits query input; it does not establish permission to that table. Table, row, and column grants within a shared source are not supported. For narrower access, use separately permissioned filtered outputs or an approved restricted action contract as described below; browser filters cannot enforce granular access.
Create a read-only Business Action only when the workflow needs a deliberate delegated contract, such as a fixed restricted result for viewers without direct source access, reusable business rules, or a named live connector call unavailable through the query API. An explicitly requested action-only boundary must stay intact; do not add direct source grants to bypass it. Do not wrap ordinary queries in read actions just to supply a screen with data. Action invocation permission does not grant direct source access, and the app assistant requires confirmation before invoking a bound action, including a read action.
A Google Drive connection imports individual data_ datasets. Discover those datasets and inspect the selected file and table before writing its query. Keep verified source and table IDs in app configuration instead of rescanning every connected file on each visit.
Establish record identity and source precedence separately when combining systems. Keep unmatched or ambiguous records visible without inventing matches or conclusions. Preserve source IDs, record IDs, dates, match rules, and freshness in query results or action output so a user can inspect the evidence.
Use filtered outputs for role-based reads
For role-based reads, create a separate Data Flow output for each audience. Filter rows and select allowed columns in the server-side transformation, share the output with its viewers, and grant the app Read on that output. Query the output’s source ID; keep the underlying database or connector restricted.
For example, give agents their own filtered deal outputs and managers a team output. Every table and historical output must fit its audience (selecting a table or adding a browser WHERE clause does not narrow permission). Restrict transformation editing and execution, and check for broader inherited grants before sharing.
Keep filters, sharing, and refresh aligned with roster or ownership changes. Materialized outputs can retain old assignments until refreshed. These grants cover each output as a whole; native row-level read policies on shared sources and expanded RBAC are coming soon.
For a caller-specific check against current database records, use db.read in an approved Business Action and return only allowed fields. Follow the business-actions guide, section “Read managed database rows for the current caller,” for source bindings, trusted identity, and read limits.
Approve and revoke app access
| Principal | Required access | How to arrange it |
|---|---|---|
| Authoring API key | App creation/write for authoring; app admin and target grant-management authority when approving app grants. | A trusted authoring environment. The key does not inherit its creator’s permissions. |
| App | Read on exact approved source IDs and explicit Run on each bound action. | client.apps.setGrant(appId, resourceId, { level, operations }). Use operations for concrete actions. Ordinary source reads need no revision binding. |
| Viewer | Workspace access, app read, source read for direct queries, and invocation permission for actions they may run. | Permute sharing or client.permissions through an authorized management client. Hosted app, delegated action, MCP, and connector sessions cannot manage grants. |
| Business Action | Declared database tables, connector bindings, or SDK capabilities approved by their resource administrators. | Publish the reviewed definition and pin its exact revision in the app. Invocation does not grant the caller raw source access. |
Create a permission matrix before granting access. Enumerate exact source IDs and every table or file exposed by a whole-source grant (including data used by other apps). Ask the source administrator to approve that scope. If it is too broad, request a separate approved source or deliberate restricted action contract; never turn a rejected table grant into a whole-source grant automatically.
App grants apply to all published revisions, including pages already open. Revoking a grant blocks subsequent requests without publishing a new site. Saving or restoring a revision does not recreate grants. To revoke, send the same PUT request with level: null; app admin permission is sufficient.
Each request must fit the signed-in user’s permissions and the app’s current grants. Action calls also require a revision pin in the served app release; queries do not require a source binding. A grant to invoke an action does not grant raw access to its database or connectors. The action retains its separately approved execution scope (the caller only needs invocation permission).
Concrete action grants distinguish Can view (business_action.read_metadata) from Can run (business_action.read_metadata plus business_action.invoke). Pass operations with client.apps.setGrant to choose these rights explicitly. App invitations add missing action operations with their own approved expiry, preserving the recipient’s existing operations and deadlines.
Omit subResourceId when creating or updating any grant. The shared grant contract rejects scoped grants across databases, datasets, connectors, and operation outputs until discovery and reads enforce them. The field remains available only to revoke an existing scoped grant with level: null. Granting whole-resource access is a separate administrator decision, never an automatic fallback.
# Use an app and target administrator’s API key outside the browser.
curl -X PUT "https://api.permute.ai/v1/apps/$PERMUTE_APP_ID/grants/$PERMUTE_DATABASE_ID" \
-H "Authorization: Bearer $PERMUTE_API_KEY" \
-H "X-Workspace-Id: $PERMUTE_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"level":"read"}'
# Use the action’s required invocation level (write in this example).
curl -X PUT "https://api.permute.ai/v1/apps/$PERMUTE_APP_ID/grants/$PERMUTE_ACTION_ID" \
-H "Authorization: Bearer $PERMUTE_API_KEY" \
-H "X-Workspace-Id: $PERMUTE_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"level":"write"}'Read the current user, query and invoke from the frontend
Bundle this code into your frontend. PermuteAppClient uses the visitor’s existing Permute sign-in session and the page’s revision-specific base URL. Keep the deployment API key out of browser code. The query needs a database with approved app and viewer read access; action calls also need a published action pinned to the app revision.
The browser SDK calls the API on the app’s own origin, including custom domains, using its HttpOnly session cookie. HTTP examples use an authenticated app cookie jar, the app origin, and the published revision; browser callers do not read the cookie. Unsafe requests require an exact matching Origin.
Call app.me() to display the current signed-in user’s id, name and email. It uses the app session, checks current membership and app read access, and returns no organization or workspace directory. Password demos have no user identity and return 403. The HTTP equivalent is GET /v1/me on the app hostname, with its session cookie.
Queries require current source read permission for both the signed-in user and the app. Action calls require the action’s declared invocation permission and execute its delegated scope. Reuse the exact requestId and input after an uncertain response; the browser client does not retry writes automatically. A 401 means the visitor needs to sign in again.
import { PermuteAppClient } from '@permute/sdk/app';
const app = new PermuteAppClient();
const user = await app.me();
console.log('Signed-in user:', user.id, user.name);
const rows = await app.query({
sourceIds: ['dbas_...'],
sql: 'SELECT id, name FROM app.customers',
limit: 100,
});
console.log(rows.rows);Verify the app assistant as the intended viewer
New apps start with the assistant off. Enable it under App details → App assistant and publish the change before testing it as a viewer.
The built-in assistant uses the same source read boundary as app.query(): current viewer permissions intersected with current app grants. An app description, a successful deployment, or a working read action does not establish direct source access. The assistant cannot inspect rendered page data or unsaved frontend state.
Before release, sign in as a representative viewer and call app.sources.list(). Confirm that the expected source is listed, inspect it with app.sources.get(sourceId), and run a bounded query such as a customer count. Ask the assistant the same question and inspect its citation. Repeat with a viewer who has no source access to verify denial. Testing only with the builder or an administrator can hide missing viewer permissions.
If the source list is empty, have an app admin check the app’s source grants and the viewer’s read permission in the correct workspace. Check whole-resource scope for every source type; table-specific grants do not authorize source discovery or queries. Then check source readiness and the API environment. Empty results describe what this viewer can access through this app, not whether the workspace contains data. Do not reconnect existing data or create read actions to work around an unexplained empty list.
Action-only apps can offer their bound actions through the assistant after viewer confirmation. To support open-ended source questions, an administrator must approve source access for both the app and viewer; this changes the access boundary and must not happen as an automatic repair.
const permitted = await app.sources.list();
console.log(permitted.items.map(({ id, name, type }) => ({ id, name, type })));
// Use the verified source ID and table from your app configuration.
const catalog = await app.sources.get('dbas_...');
const count = await app.query({
sourceIds: [catalog.source.id],
sql: 'SELECT COUNT(*) AS customer_count FROM app.customers',
limit: 1,
});
console.log(count.rows);