Operation

Assign Role

POST/user-accounts

Give a user a role in your organisation. Roles bundle together permissions, so assigning a role grants all the permissions it contains. A user can have multiple roles if they need different capabilities. This is how you give people access to do things in Backstage.

When to use this

Promoting a user to admin
Giving someone event management capabilities
Adding box office access to an existing user

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 assigned 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

Users can have multiple roles. Permissions are additive-they get everything from all their roles.

Tip

Check `getMyPermissions` to see the effective permissions after assigning a role.

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Assign Roleconst result = await client.role.assignRole({ /* request body */ });console.log('Operation completed:', result);

Response 201

{
  "assignment": {
    "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
    }
  }
}