/v1/workspaces/{workspace_slug}/rolesAuthCreate a new custom role. Cookie/JWT only — role 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.
Headers
Idempotency-KeystringOpaque 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*stringRole name. Free-form; not URL-significant.
Example: "BillingAdmin"
descriptionstringOptional human-readable role description.
Example: "Manages billing and reads invoices."
policyarrayIAM-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_idstringOptional 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 · uuidId of the role.
name*stringRole name. System role names are `owner`/`admin`/`member`.
description*stringWhat the role is for, when set.
is_system*booleanTrue for built-in system roles (owner/admin/member); false for custom roles.
policy*arrayEffective IAM-style policy. When `policy_id` is set this is the bound managed policy; otherwise it is the inline policy column.
policy_id*string · uuidManaged 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"
}