Operation

Update User's Account Roles

PUT/user-accounts

Change which roles a user has for a specific account. You can add new roles, remove existing ones, or replace them entirely. This is how you promote someone from viewer to editor, or grant additional permissions. Changes take effect immediately-the user's permissions update on their next API request.

When to use this

Promoting a user to a higher role
Granting additional permissions for a project
Adjusting access after a team restructure

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

Roles 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

Note

Changes are immediate-no need for the user to log out and back in.

Important

Be careful when removing roles-the user loses those permissions instantly.

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Update useraccountroleconst updated = await client.useraccountroles.update('{{USERACCOUNTROLES_ID}}', {  name: 'Updated Name',  // Add fields to update});console.log(`Updated useraccountrole: ${updated.name}`);

Response 200

{
  "assignments": [
    {
      "id": "uar_abc123",
      "organisationId": "org_xyz789",
      "userId": "usr_abc123",
      "accountId": "acc_xyz789",
      "roleId": "rol_system_event_manager",
      "createdAt": "2024-01-15T10:30:00Z",
      "user": {
        "id": "string",
        "email": "string",
        "firstName": "string",
        "lastName": "string"
      },
      "account": {
        "id": "string",
        "name": "string"
      },
      "role": {
        "id": "string",
        "name": "string",
        "isSystemRole": true
      }
    }
  ]
}