PermuteDocs
Go to Permute

Get started

Authentication

Authenticate API and hosted app requests, configure organization SAML SSO and SCIM Users, and manage resource access grants.

Sign in to the CLI and SDK

The CLI ships with @permute/sdk. Run it with bunx and approve the connection in Permute. Device login works from another computer (confirm the code matches your terminal).

bash
bunx @permute/sdk auth login
# Or approve from another computer:
bunx @permute/sdk auth login --device-code --no-browser
bunx @permute/sdk auth status
bunx @permute/sdk auth logout

Choose an organization, optionally limit the connection to one workspace, then select resources and permissions. Each request must fit both your approval and your current access. For organization-wide logins, use client.withWorkspace(id) for workspace API calls.

Credentials stay in your operating system’s credential store. The SDK renews access automatically, with no fixed maximum login lifetime. Thirty days without renewal ends the login. Company sign-in rules may require earlier authentication.

typescript
import { OAuthLogin } from '@permute/sdk/auth';

const client = await new OAuthLogin().client();
const workspace = client.withWorkspace('wksp_...');
const apps = await workspace.apps.list();

Local stdio MCP can reuse this login when no API key is configured. Hosted app and hosted MCP sessions stay bound to their own access scopes. Log out to revoke the CLI login and remove its local credentials.

Named login profiles

Use @permute/sdk@^0.11.0 to keep separate approved logins for different accounts or tasks with --profile NAME. Each profile has its own credentials, renewal and logout; the existing login is default. A profile name does not grant a role or permissions (approve its actual access in Permute).

bash
bunx @permute/sdk auth login --profile support --device-code --no-browser
bunx @permute/sdk auth profiles
bunx @permute/sdk auth status --profile support
bunx @permute/sdk auth logout --profile support

Use new OAuthLogin({ profile: 'support' }) in Node.js, or set PERMUTE_PROFILE=support for an agent or local stdio MCP process. An explicit profile overrides the environment; no selection uses default. Profiles use 1–64 lowercase letters, numbers, underscores or hyphens, starting with a letter or number. Selecting a missing profile fails instead of using another login. Listing names does not open the credential store or prove the sessions remain valid.

Request specific login access

Login accepts --organization ID, --workspace ID, and --access-file PATH. The JSON file can include organizationId, workspaceId, and permissions using the same selections as API-key creation. SDK callers pass that object as requestedAccess to OAuthLogin before starting device or browser login. The person can approve less than requested.

The same browser can recall settings from a prior session and highlight new or increased permissions. It stores only a non-secret session ID; the server checks ownership before returning the settings. Each new login still needs confirmation (including the device code). Remembered settings do not change existing sessions.

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.

New keys expire after one week by default. Choose 1 day, 1 week, 1 month (30 days), or a custom expiration date and time. Forever removes the fixed deadline and shows a warning. New keys also expire after 30 days without use; change this interval or turn it off in Advanced settings. Each authenticated request restarts the inactivity clock (never-used keys count from creation), and whichever expiry comes first ends access. Existing keys keep their expiration settings.

Manage connections and browser sessions

Open Your Profile → Connections to review browser, CLI and MCP logins across organizations. Filter by type and by All, Connected or Inactive (expired and disconnected logins). Browser entries identify the platform or hosted app and mark your current login as This session. Sign out ends one browser login and its ability to renew; signing out the current session returns you to sign-in. Other logins stay active.

Organization administrators can review tenant-bound CLI and MCP logins in People & access → Connections. View access shows the approved boundary; current resource permissions still apply. Disconnect ends one login and its renewal without changing MCP endpoint settings. Browser sessions remain personal because a platform login can span organizations.

Authenticate a request

Send the key in the standard bearer authorization header.

http
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_.

http
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.

typescript
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',
});

Organization SAML SSO and provisioning

Organization SSO uses SAML 2.0 with SCIM Users provisioning. Owners and organization admins configure it in Organization settings → Enterprise identity. Start in Optional mode, provision directory identities, and link them to existing Permute accounts. Local MFA remains required after SAML sign-in; test administrator sign-in and owner recovery before selecting Required mode.

Providers must support SP-initiated sign-in, signed SAML responses, and a persistent NameID matching the SCIM externalId. For Google Workspace, use a custom SAML app; automatic user provisioning still needs verification. Work with Permute to verify Microsoft Entra ID or Okta sign-in, provisioning, and offboarding in your tenant before requiring SSO. Confirm availability in your target environment before rollout.

SCIM provisions users and their active status (not groups, roles, or entitlements). Just-in-time account creation and IdP-initiated sign-in are not supported. SSO establishes identity; source permissions, app grants, and action invocation permissions remain separate. Machine API keys retain their own grants and revocation controls.

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 within a shared source are not supported by current source query APIs, including databases, datasets, connectors, and operation outputs. For narrower reads, share separately filtered Data Table or Data Flow outputs while keeping broader sources restricted, or use an approved caller-filtered Business Action. Existing scoped app grants can be revoked with level: null and their original subResourceId; other scoped grants use the permission deletion API.

Follow the filtered-output guide to set up role-based reads, or the Business Action example for caller-specific database reads without direct database access.

Use Permute sharing or an authorized management client to arrange viewer permissions. The SDK exposes client.permissions.list, create, update, delete, and inspect; app grants also have dedicated app APIs. These management calls require the client’s own resource and delegation authority and exclude hosted app, delegated action, MCP, and connector sessions. 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.

Use least privilege. Give production integrations only the workspaces and actions they require.

Understand authorization errors

App and Business Action permission failures can include permission_denied with details for the requested operation, required level, and reason. Both SDK clients retain these on PermuteApiError.details (details are optional).

  • caller_permission_required: the caller needs permission for this operation.
  • application_grant_required: the app needs its own grant.
  • source_delegation_required: authorizing an action’s source capabilities requires source admin access.
  • declared_capability_required: the action’s approved scope does not permit this operation.

These explanations appear only where access checks permit disclosure. Missing, unreadable, and foreign resources return the same 404 response. Opening an app does not grant access to its linked data; ask an administrator to review the relevant viewer and app grants. There is no automatic access-request submission.