Roles

Create a role

curl -X POST https://api.subscriby.net/v1/roles \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
        "code": "support-agent",
        "name": "Support Agent",
        "description": "Answers tickets, cannot touch billing",
        "permissions": ["support-conversation:view-any", "support-conversation:update"]
      }'

Choose the code deliberately. code is the stable identifier permissions are addressed by. It must be unique within the team and cannot be changed afterwards: renaming one would detach every assignment that referenced it. Only name, description and the permission set are mutable.

permissions accepts codes from the permission catalog in entity:action form. An unknown code is refused rather than silently dropped, so a typo fails loudly instead of creating a role that grants less than you think. Omit the field for a role that grants nothing yet.

Answers 201 with the role and emits role.created.

post/v1/roles

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/roles
  • Auth: HTTP bearer

Headers

Idempotency-Keystring uuid required

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Request body

team_idstring uuid required

The team to create the role in; the caller must belong to it, and a team outside their account answers 404. Prohibited on update: a role cannot be moved between teams.

codestring required

The stable identifier permissions are addressed by, up to 255 letters, numbers, dashes and underscores, unique within the team and immutable afterwards: renaming one would detach every assignment that referenced it. Prohibited on update.

namestring required

The display name, up to 255 characters.

descriptionstring nullable

What the role is for, up to 255 characters; null clears it.

permissionsstring[]

The permission codes the role grants, in entity:action form. Sending it sets the role's permissions to exactly this list; omit the key to leave the existing set untouched. Omit it on create for a role that grants nothing yet.

Response

The role resource as a 201.

Example response

{
  "data": {
    "id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "code": "manager",
    "name": "Manager",
    "description": "Manage plans, resources, and subscribers",
    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "permissions": [
      "project:view"
    ],
    "created_at": "2026-05-18T10:05:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.