Platform API reference

Platform API · Workspace-Policies

patch/v1/workspaces/{workspace_slug}/policies/{policy_id}Auth

Update a managed policy. Owners and admins; a policy bound to a role, or a preset policy, only an owner can edit. Cookie/JWT only — policy authoring is a human-admin surface.

Path parameters

workspace_slug*string

Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve("acme")`); the product APIs bind `workspace_id` instead.

policy_id*string · uuid

Id of the policy.

Request body

namestring

Policy name (1-64 chars, alphanumeric + space/underscore/hyphen). Unique per workspace.

Example: "mail-readonly"

descriptionstring

Optional human description. Pass `null` to clear an existing description on PATCH.

Example: "Read-only access to all Mail resources"

policyarray

IAM-style policy. Empty array means "no permissions" — useful as a placeholder before granting any actions.

Example: [{"effect":"allow","actions":["mail.read","mail.list"],"resources":["*"]}]

Response · 200 Updated policy. `bound_key_count` is the number of live API keys the change applies to.

id*string · uuid

Id of the policy.

workspace_id*string · uuid

Id of the workspace that owns the policy.

name*string

Name of the policy, unique in the workspace.

Example: "mail-readonly"

description*string

What the policy is for, when set.

policy*array

IAM-style policy statements bound to this managed policy.

preset_key*object

The workspace-key preset this policy was created from, or null for a policy a person wrote. Minting a key with `preset` creates this policy once per workspace and reuses it. It stays set after the policy is edited, so show it as "based on preset".

Example: "mail-send"

created_by*string · uuid

Account that authored the row. Only revealed to callers with `workspace.audit.read`; plain members see null.

created_at*string · date-time

When the policy was created.

updated_at*string · date-time

When the policy was last changed.

binding_count*object

Counts of currently-bound consumers — surface this in delete-confirm UX so the operator sees cascade impact.

bound_key_count*number

Live (not revoked, not expired) API keys bound to this policy — the keys a save or delete affects. Show it in the confirm step before saving or deleting.

Example: 3

Example

Request

PATCH https://api.platform-auth.productcraft.co/v1/workspaces/{workspace_slug}/policies/{policy_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "mail-readonly",
  "description": "Read-only access to all Mail resources",
  "policy": [
    {
      "effect": "allow",
      "actions": [
        "mail.read",
        "mail.list"
      ],
      "resources": [
        "*"
      ]
    }
  ]
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "name": "mail-readonly",
  "description": "string",
  "policy": [
    {
      "effect": "allow",
      "actions": [
        "social.read",
        "social.list"
      ],
      "resources": [
        "*"
      ]
    }
  ],
  "preset_key": "mail-send",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "binding_count": {},
  "bound_key_count": 3
}