Skip to content
Docs
Open Backstage
Operation

Update Role

PATCH/roles/{id}
Change a role's name, description, or permissions. Use this to adjust what a role can do. Any users with this role will immediately get the updated permissions. You can add or remove individual permissions, or replace the whole list.

When to use this

  • Adding new permissions as your app grows
  • Tightening security by removing unnecessary access
  • Renaming a role to better reflect its purpose

Path parameters

idstringRequired
Role ID

Headers

Idempotency-KeystringOptional
Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

Returns

Role updated successfully

Errors

400
Bad Request - Invalid input
401
Unauthorized - Authentication required
403
Forbidden - Insufficient permissions
404
Not Found - Resource not found
500
Internal Server Error

Every error names its code and links to it. All error codes

Notes

Important
Changes affect all users with this role immediately. Double-check before removing permissions.
Note
System roles (like "Owner") can't be modified.

Related

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Update roleconst updated = await client.role.update('{{ROLE_ID}}', {  name: 'Updated Name',  // Add fields to update});console.log(`Updated role: ${updated.name}`);
Response 200
{
  "id": "rol_abc123",
  "organisationId": "org_xyz789",
  "name": "Event Manager",
  "description": "Manages events and related resources",
  "isDeleted": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z",
  "permissions": [
    "events.*",
    "venues.read:all",
    "orders.read"
  ],
  "isSystemRole": false
}

Try it in test mode

Path parameters
Role ID