November 4, 2026: Manage connections and browser sessions
Review browser, CLI and MCP logins in Your Profile → Connections, with independent status and type filters. Browser sessions include existing platform and hosted-app logins, identify This session, and support confirmed sign-out of one login (including its renewal). Organization administrators retain a tenant-bound CLI/MCP view under People & access. Existing resource permissions and session lifetimes stay in effect.
0.9.0: Import CSV files into custom datasets
dataset.replaceTable() now accepts CSV and CSV.gz files as disk-backed Blobs. Add a new named table or replace an existing table while keeping the other tables in the dataset. With Node.js 24 or later, use openAsBlob to upload a local file without loading all its bytes into memory. Existing row-array calls continue to work; the SDK splits large NDJSON batches to fit the upload chunk limit.
Custom dataset writes accept up to 5 GiB of uploaded bytes (compressed bytes when using gzip) and 10 GiB after decompression. Complete tables remain limited to 10 million rows and 15 minutes of processing. Wide records retain separate columns. Upgrade to @permute/sdk@^0.9.0 and follow the custom dataset guide for local files, folders of tables, gzip, schema checks, and REST examples.
client.operations.getSource() now exposes incremental settings, and client.operations.updateSource() accepts them for keyed Data Tables that process changed source rows. See the changed-row processing guide for setup and rebuild behavior.
November 3, 2026: Expire unused API keys
New API keys expire after 30 days without use by default. In Advanced settings, choose 1–365 days or turn inactivity expiry off. Each authenticated request restarts the clock; a key past its cutoff cannot restart it. The earlier of fixed and inactivity expiry applies (Forever removes only the fixed deadline). Existing keys keep their current settings. Key lists and permission details show the effective expiration.
0.8.1: Fewer Keychain prompts
CLI and SDK sign-in reuse credentials in memory between API requests instead of reading the operating system’s credential store on every call. Credentials reload before renewal and when another process renews, replaces or removes the saved login. Tokens remain in the OS credential store (with no plaintext fallback), and current server permissions and revocation still apply. Upgrade to @permute/sdk@^0.8.1; existing saved logins continue to work.
Before accessing the credential store, the CLI prints the issuer and Permute entry name to stderr. Embedded SDK applications can show their own notice with onCredentialStoreAccess; the SDK stays silent by default.
0.8.0: Scoped sign-in and permission workflows
The SDK now includes the permute CLI and a Node-only @permute/sdk/auth export. Sign in through your browser or approve a device code from another computer. Choose an organization, optionally limit it to one workspace, then select resources and permissions. Credentials stay in the operating system’s credential store and renew within that approval; current permissions still apply. Existing API-key clients continue to work.
client.permissions adds permission listing, inspection, creation, editing and revocation. client.accessRequests supports requesting access and reviewing requests. Apps and Business Actions also expose revision-bound publication requests, so draft editors can ask an authorized publisher to release a specific candidate. Each workflow checks the caller’s current resource and administrative authority.
Upgrade and sign in
Use Node.js 20 or newer. With an organization-wide login, select a workspace with client.withWorkspace(id) for workspace API calls. Local stdio MCP can reuse the saved login (set PERMUTE_WORKSPACE_ID for an organization-wide approval). Hosted app and hosted MCP sessions keep their own access scopes. See CLI and SDK sign-in for renewal, logout and SDK examples.
bun add @permute/sdk@^0.8.0 bunx @permute/sdk@0.8.0 auth login # Or approve from another computer: bunx @permute/sdk@0.8.0 auth login --device-code --no-browser
November 3, 2026: Confirm API-key revocation
Revoking an API key in Settings now opens a confirmation that names the selected key and explains that anything using it will immediately lose access. Cancel leaves the key unchanged. The confirmation uses the same destructive-action dialog as other access settings.
0.7.0: App source and build revisions
App revisions now store project source (including lockfiles), build instructions and compiled output together. Source checkpoints advance the draft without changing the live app. Publication requires a build paired with the current source and build instructions; restoring a revision recovers both manifests. Builds run locally, and the pairing is declared by the uploader.
Invited editors can use Download source in App details with their platform user session. The ZIP preserves file bytes and executable flags, with build instructions and the observed draft token outside the project folder. Source downloads require current App write permission. SDK credentials need their own grants; user invitations do not grant API keys access.
The Node/Bun SDK adds checkoutApp() and saveAppSource() in @permute/sdk/deploy, plus client.apps.sourceFile() for exact-revision file reads. Source capture applies root and nested .gitignore rules and excludes credentials, dependencies, build output and personal agent state. Source allows 1,000 files and compiled output allows 200; each manifest allows 4 MiB per file and 50 MiB total. Filename exclusions do not scan file contents for secrets.
Upgrade existing App deployment scripts
Breaking authoring change: client.apps.saveSite() requires a complete source manifest and build instructions. deployApp() requires a source directory, build recipe and explicit expectedDraft token retained from checkout or a reviewed draft. Compiled-only save requests fail against the updated API. Existing published apps continue serving their compiled files, and older compiled-only revisions remain valid restore targets. No database migration or new version pointers are required.
import { deployApp } from '@permute/sdk/deploy';
// Build locally. Retain expectedDraft from checkout or a reviewed draft.
await deployApp(client, {
appId,
expectedDraft,
directory: './dist',
source: {
directory: '.',
build: {
command: 'bun run build --base=./',
outputDirectory: 'dist',
runtime: 'bun@1.3.12',
},
},
});SDK 0.7.0 includes the SDK additions in these dated entries; source helpers also require an API deployment with the source contract. See the source checkout and deployment guide for draft checkpoints, conflict handling and publication.
bun add @permute/sdk@^0.7.0
October 13, 2026: Business Action SDK delegation and enterprise sign-in
Business Actions can call declared workspace SDK methods through platform.withStep(stepId). Authors declare allowed methods and resource permissions, and each call uses a stable step ID for replay. File dataset creation can return a signed upload target for the browser to send bytes directly to storage. Action sources also support warehouse reads across processed files, synced connectors and operation outputs; these reads use current available data. Named connector bindings authorize provider calls separately.
Publishing requires authority to delegate the selected resources. Callers need the action’s invocation permission; they do not need direct access to its delegated sources. Hosted calls additionally require App access, an App invocation grant and an exact action revision binding. See the Business Actions guide for execution limits and retry rules.
Organization SAML SSO and SCIM user provisioning now use current organization identity policies. Sign-in and session checks enforce required SSO and deny suspended or deleted directory identities. See organization SSO setup for provider requirements, rollout checks, and identity boundaries. SCIM does not provision groups, roles, or entitlements.
October 11, 2026: Hosted session renewal and logout
Hosted Apps share platform session renewal, refresh rotation and logout revocation. Current App access and resource permissions are checked on requests; an older published release does not retain revoked access. Users of apps migrating from opaque cookies must sign in again. Legacy hosted query, action and profile routes forward to the shared public API; rebuild older browser bundles when adopting the updated SDK.
October 8, 2026: App assistant and shared chat API
Signed-in Apps include a platform assistant overlay that reads permitted sources and prepares bound Business Actions for user confirmation. Configure it through versioned chat.enabled App settings. Shared-password demos receive no assistant. Conversations use /v1/chats with further turns, cancellation and action decisions; chats and /v1/me require user authentication.
The updated browser SDK exposes source discovery, viewer profiles and chat methods through the hosted user session. Queries intersect App grants with viewer permissions, and action decisions retain the release’s pinned revision. The assistant cannot see page DOM or unsaved frontend state. See the App assistant guide.
October 6, 2026: App domains, access settings and branding
Organization admins can connect a dedicated App namespace, then App admins can assign a subdomain to an App. Address changes use the current expectedUrl and take effect without publishing content. The generated Permute URL remains available. The updated SDK includes client.apps.address() and client.apps.setAddress().
Access settings support Permute sign-in and shared-password demos. Password mode serves published frontend files only and denies queries and actions; access changes invalidate existing sessions without republishing. Versioned login appearance and favicons apply when their App revision is published. See the App guide for namespace setup, branding and permissions.
0.6.0: App resource grants
Inspect and manage app permissions with client.apps.listGrants() and client.apps.setGrant(). Grants use the existing resource permission model, including read/write/admin levels, resource-type wildcards, and expiry. Each app request must satisfy both the app’s grants and the signed-in user’s permissions. Grant changes apply without republishing (including to existing sessions).
Scope correction: this release accepted table grants, but source discovery and queries require whole-resource access. New scoped grants are rejected across data sources; existing scoped grants remain visible and revocable. Table selection does not establish table-level permission. For current narrower-read patterns, see separately permissioned filtered outputs or caller-filtered Business Actions.
// Use a trusted management client, never an API key in browser code.
await client.apps.setGrant(appId, databaseId, { level: 'read' });
await client.apps.setGrant(appId, actionId, { level: 'write' });
const grants = await client.apps.listGrants(appId);
// Revoke the app's access to this database.
await client.apps.setGrant(appId, databaseId, { level: null });Breaking authoring change: remove sourceIds from client.apps.saveSite() requests and deployApp() options. Approve source read grants instead. Browser query requests still use sourceIds to select data; their interface is unchanged. Action bindings still pin exact revisions and require separate invocation grants. Publishing or restoring an app never creates permissions.
Adding grants requires app admin and the corresponding permission-management authority for the target. App sessions support queries and action invocation; grants alone do not enable other API routes. See the app grants guide for approval and revocation.
bun add @permute/sdk@^0.6.0
0.5.0: Deploy a build directory
The new @permute/sdk/deploy entry for Node and Bun validates a local build, uploads its files, saves a draft, and publishes through the existing versioning API. It preserves omitted source and action bindings, checks concurrent changes, and requires an explicit draft ref before replacing unpublished work. Identical published builds return changed: false without uploads or writes (including unchanged bindings).
import { deployApp } from '@permute/sdk/deploy';
const result = await deployApp(client, { appId, directory: './dist' });
console.log(result.url, result.revisionId, result.changed);Build locally and wait for app hosting to become live before calling the helper. It does not provision hosting or retry mutations. See the app deployment guide for draft conflicts, publication recovery, and retaining an uncertain action request across sign-in or a newer app release. Existing SDK entry points remain compatible.
bun add @permute/sdk@^0.5.0
0.4.0: Hosted apps, business actions, and schema versions
Deploy static frontends with client.apps: upload compiled files, save a complete manifest, and publish through client.revisions. Visitors use Permute sign-in. The new @permute/sdk/app browser entry queries declared sources and invokes pinned action revisions using that session (no API key in browser code). See the app guide.
Author and invoke typed handlers with client.actions, including approved database table and connector bindings. Actions have their own drafts, publication, and invocation permissions. Follow the business action guide for creation through execution and retry rules.
Database changes when upgrading from 0.3.x
Read and save complete table definitions with client.databases.definition() and client.databases.saveDefinition(), then publish through client.revisions. Published schemas support adding tables; existing tables cannot be changed or removed. Schema history does not include record data.
Breaking behavior: client.databases.createTable() now saves a draft and returns its revisionId. Publish the database before using the table. Direct client.databases.transact() calls require database admin permission; use an approved business action for delegated writes. The database guide includes the save and publish sequence.
Write syncs and query timings
Configure destinations, capture previews, publish, pause, and inspect delivery with client.writeSyncs. Publishing an approved preview starts external delivery and enables scheduled captures. See the write sync guide. Query responses also include timing details for source validation, initialization, loading, and SQL execution.
Inspect sources with client.sources.listTables() and client.sources.describeTable() before writing queries. Generated provider types and Providers constants now include TikTok Ads.
bun add @permute/sdk@^0.4.0
0.3.0: Hosted connector setup and SDK constants
Create customer connection links with client.connectorSessions.create() and check completion with client.connectorSessions.get(). Select a provider with constants such as Providers.HUBSPOT, or pass only connectorId to reconnect an existing source. See the hosted connector setup guide.
Breaking change: context constant names
The CONTEXT export is renamed to Context, and its keys are now uppercase. Update imports and references when upgrading from 0.2.x (for example, CONTEXT.QuickBooks becomes Context.QUICKBOOKS, and CONTEXT.HubSpot becomes Context.HUBSPOT). The old export is removed; string values and stored dataset context are unchanged.
import { Context, Providers } from '@permute/sdk';
const dataset = await client.datasets.create({
type: 'custom',
key: 'quickbooks',
name: 'QuickBooks',
context: [Context.QUICKBOOKS],
});
const session = await client.connectorSessions.create({
provider: Providers.QUICKBOOKS,
});Context names dataset context identifiers; Providers selects connector providers. Dataset context still accepts other string identifiers.
0.2.0: Databases, Data Flows, and business context
This SDK release adds managed database access and tools to author, run, and publish data workflows. Business context and revision controls are also available through the public API (subject to your API key’s permissions).
Managed databases
Use client.databases to create and inspect databases, define tables, read records, and submit transactions that insert, update, or delete records. Database creation requires an eligible Enterprise plan and database creation admin permission. Provisioning is asynchronous; read the database status before using it. Updates and deletes require the record’s version token to reject stale writes.
Data Flows and operations
Create Data Flows, connect their processing steps, and save operation code through client.dataFlows and client.operations. Run drafts and inspect completed output before publishing. Operations also support schedules and pause/resume controls; pausing preserves the schedule, and scheduling does not publish draft code. Follow the Data Flow guide for a complete example.
Facts and skills
Manage organization facts with client.facts, including business definitions, formulas, and baselines. Use client.skills for shared workspace instructions and client.organizationSkills for shared organization instructions. Facts require an organization-scoped request. The business context guide covers both interfaces.
Revision controls and dashboard source
Use client.revisions to inspect saved history, read earlier revisions, restore drafts, and publish supported resources. Check the returned capabilities before restoring or publishing; Data Flow roots support publication but have no graph history. Restoring an operation does not run or publish it. See the restore and publish guide.
Read and replace an existing dashboard’s TSX source through client.dashboards. Dashboard source saves take effect immediately. Pass the returned revision and data run on writes so newer edits are protected.
Upgrade to 0.2.0
Install the release with:
bun add @permute/sdk@0.2.0
This release adds client methods to the 0.1.2 SDK. New authoring methods require the current revision or version token where specified. On a 409 conflict, read the latest state and reconcile your changes before retrying. Check the API reference for each method’s permissions and request fields.
0.1.2: Dataset downloads and deletion
Added dataset download and deletion methods. This is the last published version before the changelog began; earlier releases are listed in the npm version history.