Roles and permissions

Every room on QueUp decides who can do what inside it. Roles are how you decide.

Part one is for anyone running a room. It assumes you have never thought about permissions before and would rather not start now. Part two is the API reference for people building bots.

The basics

• A permission is one thing someone can do, like skipping a song or deleting a message.
• A role is a bundle of permissions with a name and a colour. You hand roles to people.
• Your room starts with seven roles. Rename them, rebuild them, or delete the ones you never use.
• Someone can hold several roles at once, and they get everything those roles allow.
• You cannot lock yourself out of your own room. Whatever you do to your roles, you still own the place.

Part one: for room owners

What a permission is

A permission is one thing someone can do in your room, like skipping the song, deleting a message, locking the queue, or changing the room's name.

We define the list and there are 24 permissions. What you can do is bundle them up however you like, which is what a role is.

What a role is

A role is a named bundle of permissions with a colour attached.

Moderator
├── Delete messages
├── Mute members
├── Kick members
├── Remove someone's song
└── Lock the queue

Give someone the Moderator role and they can do those five things. Take the role away and they can't.

Roles exist so you are not handing out permissions one at a time to forty different people. Set the role up once, then hand it out.

Your room starts with seven roles

Every new room gets these. We picked them because they cover most rooms on their first day. Rename them, re-permission them, reorder them, and delete the ones you never use.

Guest is the role everyone holds

This is the one to understand properly, because it does more work than the rest put together.

Guest is your room's default role. Everyone holds it, whether or not you have given them anything else, so it sets what an ordinary listener can do. Change Guest and you have changed the room for everyone in it.

By default, Guest can see the queue, join the queue, chat, and post images and links.

Say you want a room where only a handful of people can chat. You don't need anything clever. Take Send messages off Guest, put it on a role, and hand that role out. The chat box greys out for everyone else. The same trick works for DJing, with Join the queue.

Guest is the one role you cannot fully edit.

• You can't rename or recolour it. Everyone holds it, so a custom name would make it look like a rank someone earned.
• You can't delete it. Every room needs one role that applies to everyone.
• You can't move it off the bottom. Guest grants no authority. If it ranked above another role, every member in the room would jump to that rank.

Its permissions are yours to set.

Roles add up

Someone can hold as many roles as you like. What they can do is everything their roles allow, added together.

DJ                    Moderator             What they can do
─────────────         ─────────────         ─────────────────
Join the queue        Delete messages       Join the queue
Skip                  Mute members          Skip
Send messages         Kick members          Send messages
                                            Delete messages
                                            Mute members
                                            Kick members

A second role can only ever add. There is no role that takes a permission away again. If you want someone to lose something, take the role off them, or take the permission off the role.

Higher in the list means more authority

Your role list is a ladder, and where a role sits on it is separate from what it can do.

Co-Owner      ← can manage everything below
Manager
Moderator     ← can manage DJ, VIP, and Guest. Not another Moderator.
VIP
Resident DJ
DJ
Guest

Position decides two things.

• Who somebody can kick or ban. Only people below them. Two moderators cannot kick each other.
• Which roles somebody can edit, delete, or hand out. Only roles below their own.

It decides nothing else. A role with no permissions at all can sit near the top, and a role packed with them can sit near the bottom. Plenty of rooms hand out roles for a colour or a label rather than for power.

Drag roles to reorder them. Roles at or above your own show a padlock, because letting someone rearrange the rungs above them is how people quietly promote themselves.

You can't lock yourself out

You own your room because you made it. Ownership is stored on the room itself rather than in a role, so no amount of editing roles can take it off you.

As owner you outrank every role, hold every permission, and nobody can kick, ban or demote you. You are also the only person who can delete the room.

Setting it up

Where to find it

Room settings → Moderation Tools → Roles.

The tab shows up for the owner and for anyone holding Create, edit and assign roles below their own.

Make a role

1. Hit New role.
2. Give it a name of up to 32 characters and pick a colour. Use a swatch or the picker. Any hex colour works.
3. Tick the permissions it should have.
4. Hit Create role.

New roles land at the bottom of the list, just above Guest. Drag it where you want it.

A room can have 100 roles, counting the seven it started with.

The editor has two toggles.

• Allow anyone to @mention this role. Turn it on and anyone in the room can type @role-name to ping everyone who holds it. Turn it off and nobody can ping the role by name, whatever else they can do. It starts off.
• Show this role separately in the user list. Turn it on and holders get their own heading in the sidebar. Leave it off and they stay in the Guest section with their name in the role's colour. Defaults to off.

Give someone a role

Click a name in the user list and pick Roles. Tick the roles you want them to have, untick the ones you don't.

There is no limit on how many roles one person holds. Give someone all 100 if you want. They get everything those roles allow, added together.

Roles above your own are greyed out rather than hidden, so you can always see the whole list even where you can't reach it.

Delete a role

Open the role and hit Delete role. Anyone holding it loses it and goes back to being an ordinary member. You can delete the starter roles too. Guest is the only one that can't be deleted.

Three settings that became permissions

If you ran a room before custom roles arrived, three toggles have disappeared from your settings. Each one is now a permission on your Guest role, which means you can give it to one role and withhold it from another instead of having it on or off for the whole room.

Two of those moved across on their own. One didn't, and you should know which.

Guest chat and guest embeds carried over. If you had guest chat switched off, your Guest role already has Send messages unticked. There is nothing for you to do.

The queue setting didn't. We removed "Show what DJs have queued" rather than migrating it, so if you had it switched off, your room is showing its queue to everyone right now. Take View queue off Guest to put it back how you had it.

The queue lock still works the way it always did, as a switch a moderator flips in the moment. What changed is that "guests can't queue at all" is now Join the queue on your Guest role rather than a side effect of leaving the lock on. If your lock was already on when roles launched, we took Join the queue off your Guest role so your room carried on behaving the same way.

Two rules that stop people taking your room

Read these before you hand anyone Create, edit and assign roles below their own.

Nobody can touch a role at or above their own

Someone who can manage roles can create, edit, reorder, delete and hand out any role below theirs. Not their own, not one level with theirs, and not one above.

A Moderator with role management can build a DJ role and hand it out all day. They cannot edit Moderator to give themselves more, and they cannot promote themselves past Manager.

Nobody can grant a permission they don't have

While you are editing a role, every permission you don't hold yourself is greyed out, with "You don't hold this, so you can't grant it" underneath.

Without that rule, role management on its own would hand over the room. Anyone holding it could build a role carrying Ban members, give it to themselves, and walk off with the place. Owners and QueUp staff hold everything already, so nothing is greyed out for them.

Put together, these two mean the person you promote can never outrank you using the tools you gave them. That is the whole safety model, and it is worth knowing it holds before you start handing roles out.

Some permissions bring others with them

A few permissions don't work alone. Anything that acts on the queue brings View queue along, because reordering a queue you can't see is not a thing anyone can do.

That covers Reorder the queue, Remove someone's song, Lock the queue, Remove someone as DJ, Edit moderation settings, Kick members and Ban members. Kick, ban and mute also bring View the member list.

Your role stores exactly what you ticked. Untick Reorder the queue and the View queue that tagged along goes with it, unless you ticked that one yourself.

What the permissions actually do

Room

Queue

View queue is the interesting one. Take it off Guest and the queue still shows who's coming up and where they are in line, but not what they've picked. It is how you keep a room's selections a surprise. We strip the songs out on the server rather than just hiding them in the app, so nobody can go looking.

Chat

Members

Three things about moderation that catch people out.

• Kick keeps their roles. They are out of the room for now rather than stripped of everything, and they can come back.
• Ban takes their roles away. Unbanning lets a plain member back in, so you are not quietly handing moderator powers back to somebody you threw out.
• Mute only works on people with no role. It is for quieting a chatter, not for demoting a colleague. If you want somebody with a role to stop, take the role off them.

Nobody can kick, ban or mute the room owner or QueUp staff, and nobody can moderate themselves.

Roles

There is one permission here rather than five. Splitting create, edit, delete and assign apart bought nothing, because what somebody can actually touch is decided by where they sit in the list and by what they already hold, not by which of the five they were given.

Reading the role list needs no permission at all. Names, colours and order are already on show next to everyone in the room. Changing a role is the part that needs permission.

Live streaming

Advanced

This doesn't hand over is position or ownership. An administrator still can't edit a role above their own, can't kick somebody who outranks them, and can't delete the room. Give it to people you would trust with the room itself, and nobody else.

Privacy sits behind Administrator rather than Manage room on purpose. Whether the room is private, password-protected or listed in the lobby decides who gets through the door at all, and trusting somebody to rename the room is not the same as trusting them with that.

Setting up a room from scratch

Here is the whole thing end to end, for a room where anyone can listen, a handful of people can DJ, and two people moderate.

1. Decide what a stranger can do. Open Guest. Leave Send messages and View queue ticked so people can talk and follow along. Untick Join the queue, because you want DJing to be something you hand out.
2. Build the DJ role. New role, call it whatever suits the room, pick a colour. Tick Join the queue, Join the queue while it is locked and Skip the current song. Turn on "show separately" if you want your DJs grouped at the top of the user list.
3. Keep Moderator, or build your own. The starter Moderator role already has chat and queue moderation, kick, ban and mute. If that is more than you want to hand over, untick what you don't need. Delete messages and Kick members cover most rooms.
4. Put them in order. Moderator above DJ, DJ above Guest. Drag them into place.
5. Hand them out. Click a name in the user list, pick Roles, tick the role.

You're ready to go!

When something isn't working

"I gave someone Moderator and they still can't kick anyone." Check the order of your role list. Kicking needs the kicker to sit above the person being kicked. If they are both Moderator, neither can touch the other.

"A checkbox is greyed out while I'm editing a role." You don't hold that permission yourself, so you can't hand it out. Ask somebody above you to grant it to you first.

"I can't drag a role." It is at or above your own. Only the owner can move everything.

"Someone's name is one colour but they're listed under a different heading." Those are two separate questions. The colour comes from their highest role. The heading comes from their highest role with "show separately" switched on, and if none of their roles have it they sit under Guest.

"I'm the owner but I'm not listed under Co-Owner." That is working as intended. We give the room creator no role at all, because your control comes from owning the room rather than from holding something. Give yourself a role if you want the colour and the heading.

"I've hit 100 roles and can't make another." Delete the ones nobody holds. The seven your room started with count towards the 100, so clearing out starter roles you never used gets that space back.

"I deleted a role by mistake." It's gone, and everyone who held it is an ordinary member again. Make it again and hand it back out.

"I've turned every permission off on every role." You are still the owner, so you still hold everything. Open the roles tab and put it back.

If you're still stuck, ask in our Discord.

--- ---

Part two: the roles API

Build a bot that hands out roles, checks what someone can do before it acts on their behalf, or reacts when a room's permissions change.

Building something? Join our Discord. That's where we post API changes, and an admin can tag you with the third-party developer role.

How permissions work for your bot

Read part one for the full model. Four things change how you write a bot.

Roles are per room. A role id belongs to one room and resolves to nothing anywhere else. If your bot runs in ten rooms, it holds ten separate sets of roles, and it has to look up role ids per room.

Rank limits what your bot can touch. Your bot can only manage roles below its own highest role, and only moderate members ranked below it. A bot sitting at DJ rank cannot hand out a Moderator role no matter what permissions it holds.

Your bot can only grant permissions it holds itself. If you want your bot to hand out a role carrying members.ban, the bot needs members.ban too.

Tell room owners both of those last two when you write your install instructions. Most support questions about bots turn out to be a bot placed too low in the role list.

The role object

{
  "id": "65f0a1b2c3d4e5f6a7b8c9d0",
  "roomId": "65e0000000000000000000aa",
  "templateKey": "mod",
  "type": "mod",
  "label": "Moderator",
  "position": 599,
  "color": "#00aeff",
  "permissions": ["chat.delete", "members.kick", "queue.view"],
  "isDefault": false,
  "mentionable": false,
  "displaySeparately": true
}

Roles come back highest position first. roles[0] is the role whose colour and label a client should display for someone holding several.

The actor object

Your bot's own standing in a room. It comes back from GET /room/:roomid/permissions/me and alongside the role list.

{
  "permissions": ["chat.send", "members.kick", "members.list", "queue.view"],
  "position": 599,
  "isOwner": false,
  "isGlobalAdmin": false,
  "roles": ["65f0a1b2c3d4e5f6a7b8c9d0"]
}

permissions is expanded and role.permissions is not, so compare against this list rather than against a role's own array.

Permission keys

There are 24 permissions. Fetch the catalogue from GET /permissions rather than copying this table into your code, because we add to it.

Implied permissions

Some permissions grant another because the two cannot work apart. A role that can reorder the queue has to be able to read it.

The permissions array on a role stores only what the room ticked. The permissions array on the actor object has the implied ones added. So a bot holding queue.order will find queue.view in actor.permissions and will not find it on the role that granted it.

room.admin grants everything, including permissions that do not exist yet. If your bot checks for a specific key it will find it in actor.permissions when the bot is an administrator, so you do not need a special case.

Endpoints

List the permission catalogue

GET /permissions

Public and the same for every room. Cache it for the lifetime of your process.

curl https://api.queup.net/permissions

{
  "groups": [
    {
      "key": "queue",
      "label": "Queue",
      "permissions": [
        {
          "key": "queue.order",
          "label": "Reorder the queue",
          "description": "Move people up and down the queue."
        }
      ]
    }
  ]
}

The label and description are the same strings QueUp shows room owners. Use them if your bot renders a permission picker, so your wording matches ours.

List a room's roles

GET /room/:roomid/roles

Requires a session. No permission needed, because role names, colours and order are already visible on everyone in the user list.

:roomid accepts a room id or a room URL slug, so /room/train-town works.

curl -b cookies.txt https://api.queup.net/room/train-town

{
  "roles": [ { "id": "65f0...", "label": "Co-Owner", "...": "..." } ],
  "actor": { "permissions": ["chat.send"], "position": 0, "isOwner": false }
}

This is the cheapest way to get both the room's roles and your bot's own standing in one request. Call it when your bot joins a room.

Retrieve your bot's permissions

GET /room/:roomid/permissions/me

Returns the actor object on its own.

curl -b cookies.txt https://api.queup.net/room/65e0.../permissions/me

Create a role

POST /room/:roomid/roles

Requires roles.manage, and your bot can only grant permissions it holds itself.

curl -b cookies.txt -X POST https://api.queup.net/room/65e0.../roles \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Resident DJ",
    "color": "#6bdaff",
    "permissions": ["queue.view", "queue.join", "chat.send"],
    "mentionable": false,
    "displaySeparately": true
  }'

{ "role": { "id": "65f1...", "label": "Resident DJ", "position": 128 } }

New roles land at the bottom of the list, above the default role. You cannot choose a position on create. Reorder afterwards if you need to.

Update a role

PUT /room/:roomid/roles/:roleid

Requires roles.manage, a rank above the role, and every permission you are putting on it.

This replaces the role rather than patching it. Read the role first, apply your change, and send the whole object back. Omitting permissions clears them, and omitting mentionable or displaySeparately sets them to false. label is required. color is the one field that keeps its stored value when you leave it out.

curl -b cookies.txt -X PUT https://api.queup.net/room/65e0.../roles/65f1... \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Resident DJ",
    "color": "#6bdaff",
    "permissions": ["queue.view", "queue.join", "chat.send", "queue.skip"],
    "mentionable": true,
    "displaySeparately": true
  }'

The default role rejects a changed label or color, and rejects displaySeparately: false. Its permissions are editable like any other role's.

Delete a role

DELETE /room/:roomid/roles/:roleid

Requires roles.manage and a rank above the role. The default role cannot be deleted.

curl -b cookies.txt -X DELETE https://api.queup.net/room/65e0.../roles/65f1...

{ "deleted": true }

Everyone holding the role loses it and stays in the room as an ordinary member.

Reorder roles

PUT /room/:roomid/roles/order

Requires roles.manage. This is the only way a role's position changes.

curl -b cookies.txt -X PUT https://api.queup.net/room/65e0.../roles/order \
  -H 'Content-Type: application/json' \
  -d '{"order": ["65f0...", "65f1...", "65f2...", "65fd..."]}'

Returns the full reordered list.

Three rules the server enforces. The list must name every role in the room exactly once. The default role must be last. Any role your bot does not outrank must stay at the index it already had, which means your bot cannot move itself or anything above it.

Read the current order, splice your role into place, and send the whole list back.

Assign a role

PUT /room/:roomid/users/:userid/roles/:roleid

Requires roles.manage, a rank above the role, and a rank above the target member. The target has to be a member of the room.

curl -b cookies.txt -X PUT \
  https://api.queup.net/room/65e0.../users/64aa.../roles/65f1...

{ "role": { "id": "65f1...", "label": "Resident DJ" } }

Assigning is additive. A member can hold as many roles as you give them, and assigning a second role does not remove the first.

Remove a role

DELETE /room/:roomid/users/:userid/roles/:roleid

Same permission and rank requirements as assigning.

curl -b cookies.txt -X DELETE \
  https://api.queup.net/room/65e0.../users/64aa.../roles/65f1...

Read who holds what

There is no endpoint that lists a role's holders. Read the room roster instead.

GET /room/:roomid/users

This endpoint needs the room id. Unlike the role endpoints, it does not resolve a URL slug, and passing one returns an empty roster rather than an error.

Each entry carries a roleids array with the full role objects populated, so one request gives you every member and their roles.

This endpoint is rate limited to 30 requests per 10 minutes per account. Fetch the roster when your bot joins, then keep it current from the realtime events below rather than polling.

Errors

Failures use the same envelope with the detail nested under data.

{
  "code": 403,
  "message": "Forbidden",
  "data": {
    "origin": "method",
    "details": {
      "code": 403,
      "message": "cannot grant permissions you do not hold",
      "expected": true
    }
  }
}

Read data.details.message. It is written for a person, so you can show it directly. There are no stable machine-readable error codes on these endpoints yet, so match on the status code and treat the message as display text rather than parsing it.

A 403 on assignment does not tell you whether the role or the member was the problem. Compare actor.position against the role's position to find out, treating null as unlimited.

Realtime events

Connect to the room channel to react to role changes. See the Extension API docs for how to connect and for the rest of the room's events.

On the two assignment events, user is whoever made the change and targetUser is the person whose roles changed. That matches user-kick and the other room events.

room-role-update fires on any edit, so it can change what your bot itself can do. Refetch GET /room/:roomid/permissions/me when you see one that touches a role your bot holds.

room-role-delete sends only the id. Your bot has to know which members held it, which is one reason to keep the roster in memory.

Limits

QueUp caches a member's effective permissions for 60 seconds. Your own writes clear that cache straight away, so a role you just assigned takes effect on the next request. A change made outside your bot can take up to a minute to show up in GET /room/:roomid/permissions/me. The realtime events fire immediately either way, so react to those rather than polling.