/v1/workspaces/{workspace_slug}/policies/{policy_id}AuthUpdate 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*stringSlug 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 · uuidId of the policy.
Request body
namestringPolicy name (1-64 chars, alphanumeric + space/underscore/hyphen). Unique per workspace.
Example: "mail-readonly"
descriptionstringOptional human description. Pass `null` to clear an existing description on PATCH.
Example: "Read-only access to all Mail resources"
policyarrayIAM-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 · uuidId of the policy.
workspace_id*string · uuidId of the workspace that owns the policy.
name*stringName of the policy, unique in the workspace.
Example: "mail-readonly"
description*stringWhat the policy is for, when set.
policy*arrayIAM-style policy statements bound to this managed policy.
preset_key*objectThe 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 · uuidAccount that authored the row. Only revealed to callers with `workspace.audit.read`; plain members see null.
created_at*string · date-timeWhen the policy was created.
updated_at*string · date-timeWhen the policy was last changed.
binding_count*objectCounts of currently-bound consumers — surface this in delete-confirm UX so the operator sees cascade impact.
bound_key_count*numberLive (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": [
"*"
]
}
]
}import { PlatformAuth } from "@productcraft/platform-auth";
// Reads PRODUCTCRAFT_API_KEY from the environment; administration
// calls take a person's session: { auth: { type: "bearer", token } }
const platform = new PlatformAuth();
const managedPolicyDetail = await platform.workspaces.policies.update("acme", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "Read-only access to all Mail resources" });platform.workspaces.policies.update(workspaceSlug, policyId, params?, options?): PlatformAuth.ManagedPolicyDetail
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
}