Authentication

Create an API key

In app.permute.ai, open Organization Settings, select API Keys, and choose Create API Key. Copy the key when it is created; it is shown once.

Authenticate a request

Send the key in the standard bearer authorization header.

Authorization: Bearer $PERMUTE_API_KEY

Choose a workspace

Workspace-scoped keys infer their workspace. Organization-scoped keys must include the workspace ID on data operations. Workspace IDs begin with wksp_.

Authorization: Bearer $PERMUTE_API_KEY
X-Workspace-Id: $PERMUTE_WORKSPACE_ID
Content-Type: application/json

Hosted app sessions

Hosted apps call the public API on their own origin (including custom domains). The browser SDK uses the existing HttpOnly session cookie and sends the page’s published revision. Authentication derives the user and workspace from signed app scope; resource access intersects current user permissions with app grants.

Queries, source discovery and action invocation accept scoped user sessions. Chat and basic-profile routes require user authentication; other routes keep their declared authentication requirements. Unsafe app requests require an exact matching Origin. The HTTP examples for user routes use an authenticated app cookie jar, app origin and published revision; browser callers use the SDK without reading the cookie.

Conversations use /v1/chats and preserve context across turns. /v1/answer-jobs remains one-shot analysis available to API-key clients.

import { PermuteAppClient } from '@permute/sdk/app';

const app = new PermuteAppClient();
const chat = await app.chats.create({
  action: 'send_message',
  clientRequestId: crypto.randomUUID(),
  message: 'Show the pipeline',
});

Permissions

A valid key does not bypass permissions. Each request is limited to the resources and read, write, or admin grants assigned to that key. A list endpoint only returns resources the key can read.

Apps and API keys need their own grants; they do not inherit their creator’s access. Ordinary app queries need read permission on the source for both the app and viewer. Bound actions need invocation permission on both, plus separately approved execution scope. An action grant does not grant raw source access.

New grants support whole resources and resource-type wildcards, with optional expiry. Table, row, and column scopes are not supported by current source query APIs, including databases, datasets, connectors, and operation outputs. Existing scoped app grants can be revoked with level: null and their original subResourceId; other scoped grants use the permission deletion API.

Use the app grants API for app permissions. An administrator uses Permute sharing for viewer permissions; the public SDK does not expose general user-permission mutation methods. Review a shared source’s complete contents before approving access (including tables used by other apps).

Follow the app permission matrix and test as an intended viewer before release. The built-in app assistant uses this same access boundary; building another chat interface cannot repair missing grants.