create_role

Purpose

Creates a role on a team. A role is what one collaborator is — everyone in a team holds exactly one. For a named bundle several people share, use create_group instead.

Subscriby seeds admin, manager and viewer on every new team; this adds your own.

Choose the code deliberately

code is unique within the team and cannot be changed afterwards — invitations and role assignments address it. Only name, description and the permission set stay mutable.

Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and creates nothing.

Required ability

role:create

Input schema

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": "string",
      "description": "UUID of the team the role belongs to."
    },
    "code": {
      "type": "string",
      "description": "Stable identifier, alpha-dash. Unique per team and immutable once created."
    },
    "name": { "type": "string", "description": "Human-readable role name." },
    "description": {
      "type": "string",
      "description": "Optional description of what the role is for."
    },
    "permissions": {
      "type": "array",
      "description": "Permission codes (entity:action) to grant. Omit for a role with none."
    }
  },
  "required": ["team_id", "code", "name"]
}

permissions uses the same strings as token abilities. Read subscriby://enums/ability for the catalog.

Output shape

{
  "data": {
    "id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "code": "auditor",
    "name": "Auditor",
    "description": "Read-only access to subscriptions and payments",
    "permissions": ["project:view-any", "project-subscription:view-any"]
  }
}

Emits role.created.

Example prompts

"Create an auditor role on my team that can read subscriptions and payments but change nothing."

"Add a support-agent role with access to the support inbox only."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks role:create.
TEAM_TIER_REQUIRED — the caller's platform tier does not include Teams.
RESOURCE_NOT_FOUND — no such team, or the caller is not a member.
VALIDATION_FAILED — code already used on that team, malformed code, or a permission string that is not in the catalog.

update_role
delete_role
list_roles
create_group — for a bundle several people share.
Roles API