Set an app custom address – PUT /v1/apps/{applicationId}/address

Set an app custom address

Requires app admin permission and a live app. Select a ready organization namespace and one DNS label, or set address=null to remove the custom address. Supply expectedUrl from the current address (null if absent) for concurrency control. Names are unique within the namespace. Takes effect immediately without publishing app content or changing permissions. The generated Permute URL remains available.

PUT/v1/apps/{applicationId}/address

betaapiKeyworkspace

When to use

Assign or remove a custom address for a live app.

For agents

Requires app admin and a ready organization namespace. Use a single DNS label and expectedUrl from apps.address; a conflict requires reloading and reviewing the current address. Send address: null to remove it. Changes take effect without publishing or further DNS setup. The generated Permute URL and existing permissions remain; each hostname has its own sign-in session.

Example

typescript

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

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.apps.setAddress('appl_abcdefghijklmnopqrstuvwx', {
  "address": {
    "namespaceId": "domn_abcdefghijklmnopqrstuvwx",
    "label": "crm"
  },
  "expectedUrl": null
});

Request body

json

{
  "address": {
    "namespaceId": "domn_abcdefghijklmnopqrstuvwx",
    "label": "crm"
  },
  "expectedUrl": null
}

Response

json

{
  "data": {
    "address": {
      "namespaceId": "domn_abcdefghijklmnopqrstuvwx",
      "label": "crm",
      "url": "https://crm.apps.example.com"
    },
    "canManage": true,
    "namespaces": [
      {
        "id": "domn_abcdefghijklmnopqrstuvwx",
        "hostname": "apps.example.com",
        "status": "live"
      }
    ]
  }
}