PermuteDocs
Go to Permute

Build apps

Configure app sign-in and addresses

Choose visitor sign-in or a mock-data demo, set a favicon, and configure a custom app address.

Before you start

Workflow

  1. 1Use an existing app and an app administrator’s management client. Set PERMUTE_APP_ID, PERMUTE_WORKSPACE_ID, and PERMUTE_API_KEY.
  2. 2Run the read-only setup below; the server-side snippets reuse client, appId, and required. Set DEMO_PASSWORD only when deliberately enabling a mock-data password demo.
  3. 3Organization admins configure domain ownership separately. Wait for the namespace to be ready before assigning an app address.

Example

typescript
import { PermuteClient } from '@permute/sdk';

function required(name: string): string {
  const value = process.env[name]?.trim();
  if (!value) throw new Error('Set ' + name);
  return value;
}
const client = new PermuteClient({
  apiKey: required('PERMUTE_API_KEY'),
}).withWorkspace(required('PERMUTE_WORKSPACE_ID'));
const appId = required('PERMUTE_APP_ID');
console.log(await client.apps.access(appId));

Choose visitor access

Apps default to Permute sign-in. Existing workspace membership, app permissions, user permissions and app grants continue to govern access. For a demo with mocked data, an app admin can select Shared password (demo) under App access, or use the access API below.

The password gates every frontend file, including JavaScript and direct asset URLs. Anyone admitted can inspect downloaded code and files from previously published releases. Use a separate demo app if older releases contain sensitive content. Password demos cannot query Permute data or invoke Business Actions, even with existing app grants.

Passwords must have 8 to 256 characters. The server stores a salted hash and limits password submissions to 20 per minute per app. Sessions last up to eight hours. Saving access settings applies immediately and signs out existing visitors; it does not create or publish a site revision. Restoring a site does not restore access settings. Password-free public access is unavailable.

typescript
const access = await client.apps.access(appId);
await client.apps.setAccess(appId, {
  mode: 'password',
  password: required('DEMO_PASSWORD'),
  expectedVersion: access.version,
});
// To require Permute sign-in again, read the latest access version and send
// { mode: 'permute', expectedVersion: latest.version }.
bash
# App admin API key; keep both credentials out of browser bundles.
curl "https://api.permute.ai/v1/apps/$PERMUTE_APP_ID/access" \
  -H "Authorization: Bearer $PERMUTE_API_KEY" \
  -H "X-Workspace-Id: $PERMUTE_WORKSPACE_ID"
# PUT the same URL with JSON {"mode":"password","password":"...","expectedVersion":0}.
# Use the version returned by GET. Never commit the password to source control.

Set the app favicon

In App details → Appearance, choose a square PNG up to 256 KiB, save the draft, then publish. The favicon appears in browser tabs and on both sign-in methods, independently of custom login styling. It overrides icons in the compiled site. Set favicon to null to remove the override; the site’s own icon then applies.

The favicon uses the existing app upload API and version history (no separate storage or deployment). Only the current published favicon is public before sign-in. Draft icons require app read access; historical icons are served only to authenticated visitors of that published release. Each app has its own icon; there is no organization default.

typescript
import { readFile } from 'node:fs/promises';

const current = await client.apps.get(appId);
const [favicon] = await client.apps.uploadFiles(appId, [
  { path: 'branding/favicon.png', data: await readFile('./favicon.png') },
]);
const saved = await client.apps.update(appId, { favicon, expectedDraft: current.draft });
const state = await client.revisions.list(appId);
if (state.draft?.revisionId !== saved.draft.revisionId || state.draft.sequence !== saved.draft.sequence) {
  throw new Error('Draft changed; review before publishing');
}
await client.revisions.publish(appId, { expectedVersion: state.version });

Custom app addresses

Organization admins connect a dedicated root domain or subdomain in Organization Settings → App domains. For a root domain such as example.com, replace its nameservers at the registrar with all four displayed values; remove any existing DNSSEC DS record before switching. For a subdomain such as apps.example.com, add the four displayed NS records at your DNS provider (often entered as apps) and keep your main domain’s nameservers unchanged. Existing website and email records aren’t migrated, so use an unused, dedicated domain or subdomain. Permute manages app routing and HTTPS certificate validation in the delegated zone. Keep the NS records while using the namespace; setup is asynchronous, so wait for Ready.

Once the namespace is ready, app admins can choose a name under App details → App URL. The SDK equivalent is client.apps.address(appId), followed by client.apps.setAddress(appId, { address: { namespaceId, label: "crm" }, expectedUrl: current.address?.url ?? null }). Use a namespace ID returned by the address read. Set address to null to remove the custom address. These methods require an SDK release containing apps.address and apps.setAddress; the REST routes are GET and PUT /v1/apps/{applicationId}/address.

An address assignment takes effect without republishing frontend content. Existing generated Permute URLs remain available. Each hostname has its own sign-in session; app permissions, grants, and password-demo restrictions apply on every address.

Removing the organization namespace immediately disconnects all its custom app addresses, then starts cloud cleanup. You can connect a replacement immediately while cleanup continues. Remove subdomain NS records at your DNS provider, or change root-domain nameservers at the registrar away from Permute, to allow final zone deletion after cached delegation expires. With no replacement connected, reconnecting the same namespace reuses its retained zone and nameservers while available, rechecks delegation and provisions HTTPS again. Check the displayed NS records after reconnecting and reassign app addresses; previous assignments are not restored.

This release supports one connected namespace per organization in each environment and one custom address per app. Each app occupies one subdomain level, such as crm.apps.example.com. Individual domain aliases, routing multiple apps under URL paths, and custom domains for the main Permute platform are not included. Namespace setup requires a signed-in organization admin; API keys can assign app addresses but cannot manage organization DNS ownership.