Org Admin Guide

Ranking Integration

Connect RoPerms to your Roblox group so the dashboard can promote and demote members automatically — triggered by training session passes or manual staff actions.

Overview#

RoPerms can change a player's rank in your Roblox group using one of two methods:

Cookie auth (recommended)— uses a Roblox account's session cookie plus an XSRF token to call the Groups API. More reliable in practice.
OAuth auth (fallback) — uses Roblox Open Cloud v2 OAuth with a refresh token. More modern but prone to refresh-token rotation failures in long-running deployments.

⚠Use a dedicated ranking account

Do not use your personal Roblox account for ranking. Create a dedicated bot account, add it to your group with a rank that has permission to manage ranks (usually "Ranking Bot" or similar), and use that account's credentials. Using your personal account risks it being flagged by Roblox.

1
Get the ranking account's cookie
Log in to Roblox as your ranking bot account in a browser. Open DevTools (F12), go to the Application tab, find Cookies for roblox.com, and copy the value of the .ROBLOSECURITY cookie.
2
Enter the cookie in RoPerms
In your org Settings, go to Integrations → Ranking. Paste the cookie into the Roblox Cookie field. Save.
3
Enter your Group ID
Enter your Roblox group's numeric ID (visible in the group URL on Roblox.com).
4
Test a rank change
Go to any player's profile and attempt a test rank change from the Team or Sessions page. Check the audit log for a ranking success/failure entry.

ℹCookie expiry

Roblox cookies expire after approximately 30 days of inactivity or when the account's password changes. If ranking stops working, re-generate the cookie by logging in again and updating the value in Settings → Integrations.

OAuth auth setup (fallback)#

If you prefer OAuth, go to Settings → Integrations → Ranking and click Connect via Roblox OAuth. You will be redirected to authorise the RoPerms app with your ranking account's Open Cloud credentials.

OAuth uses a refresh token that should renew automatically. However, Roblox can revoke refresh tokens unexpectedly — if ranking breaks, reconnect OAuth or switch to cookie auth.

Auto-ranking on session pass#

The most common use of ranking is automatic promotion when a trainee passes a training session.

1
Configure a pass rank on the session type
In Settings → Session Types, edit the relevant type and set a Pass Rank (the Roblox group rank number to promote to).
2
Run a session
When a trainer marks an attendee as Pass, RoPerms automatically calls the ranking API to promote the player to the configured rank, provided the player's current rank is below the pass rank.
3
Check the audit log
A rank.change audit entry is written with the old rank, new rank, and the session ID that triggered the change.

Manual rank changes#

Org admins can also trigger rank changes manually from a player's profile by using the Change Rank action. Provide the target rank number and confirm. The change is applied immediately using the configured ranking credentials.

Rank guard#

The rank guard prevents staff from taking moderation actions (ban, kick, warn) against players whose group rank is higher than their own. This is enforced on the server regardless of how the action is initiated. Org admins bypass the rank guard entirely.

Troubleshooting ranking#

Cookie expired — re-authenticate by logging in as the bot account and copying a fresh .ROBLOSECURITY cookie.
Bot account lacks permission— the bot must have at least the "Rank Members" permission in your Roblox group. Check the group role settings.
Target player's rank is above bot's rank— Roblox does not allow ranking members to a rank above or equal to the ranker's own rank. Ensure the bot is high enough in the group hierarchy.
OAuth refresh failure — reconnect OAuth in Settings → Integrations, or switch to cookie auth.

←

Orders

Troubleshooting

→