Roles

Update a role

curl -X PATCH https://api.subscriby.net/v1/roles/$ROLE_ID \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Senior Support Agent", "permissions": ["support-conversation:view-any"]}'

Permissions replace, they do not merge. Sending permissions sets the role's permissions to exactly that list; anything omitted is revoked. Omit the key entirely to leave the existing set untouched while changing only the name or description.

Answers 200 with the role and emits role.updated.

patch/v1/roles/{role}

Request

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

Path parameters

rolestring uuid required

The role, resolved by the route binder.

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 updated role resource.

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.