Platform API reference

Platform API · Workspace-Roles

post/v1/workspaces/{workspace_slug}/rolesAuth

Create a new custom role. Cookie/JWT only — role 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.

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body returns the first response with `Idempotent-Replay: true` instead of creating a second resource. The SDKs send one on every create.

Request body

name*string

Role name. Free-form; not URL-significant.

Example: "BillingAdmin"

descriptionstring

Optional human-readable role description.

Example: "Manages billing and reads invoices."

policyarray

IAM-style policy granting the role its permissions. Same wire shape as PAK policies. Omit or pass `[]` for a no-permissions role.

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

policy_idstring

Optional managed-policy id to bind the role to. When set, the role's effective policy comes from the bound managed policy and `policy` (inline) must be omitted.

Example: "11111111-1111-1111-1111-111111111111"

Response · 201

id*string · uuid

Id of the role.

name*string

Role name. System role names are `owner`/`admin`/`member`.

description*string

What the role is for, when set.

is_system*boolean

True for built-in system roles (owner/admin/member); false for custom roles.

policy*array

Effective IAM-style policy. When `policy_id` is set this is the bound managed policy; otherwise it is the inline policy column.

policy_id*string · uuid

Managed policy ID if the role is bound to one, else null.

Example

Request

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

{
  "name": "BillingAdmin",
  "description": "Manages billing and reads invoices.",
  "policy": [
    {
      "effect": "allow",
      "actions": [
        "mail.*.read"
      ],
      "resources": [
        "*"
      ]
    }
  ],
  "policy_id": "11111111-1111-1111-1111-111111111111"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "description": "string",
  "is_system": false,
  "policy": [
    {
      "effect": "allow",
      "actions": [
        "social.read",
        "social.list"
      ],
      "resources": [
        "*"
      ]
    }
  ],
  "policy_id": "00000000-0000-0000-0000-000000000000"
}