How to Automate Discord Role Assignments using the API

Understanding the Discord API

Setting Up Discord API Authentication

Discord bots authenticate with a Bot Token — a static credential that does not expire until you explicitly reset it in the Developer Portal. Include it in every request as Authorization: Bot <token>. There is no OAuth refresh flow for bot tokens; rotation is manual.

1. 1Go to https://discord.com/developers/applications and click New Application.
2. 2Name your application, then open the Bot tab in the left sidebar.
3. 3Click Reset Token to generate your bot token — copy it immediately, it is shown once.
4. 4Under Privileged Gateway Intents, toggle on Server Members Intent only if you need GUILD_MEMBER_ADD events for reactive role assignment.
5. 5Open OAuth2 > URL Generator. Select scopes: bot and applications.commands. Under Bot Permissions, check Manage Roles.
6. 6Copy the generated URL, open it in a browser, and invite the bot to your test server.
7. 7In your server's role settings, drag the bot's auto-created role above every role you want it to manage.
8. 8Store the token as DISCORD_BOT_TOKEN in your environment variables — never hardcode it.

1import os
2import requests
3
4BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
5BASE_URL = "https://discord.com/api/v10"
6
7headers = {
8    "Authorization": f"Bot {BOT_TOKEN}",
9    "Content-Type": "application/json"
10}
11
12# Verify the token is valid
13response = requests.get(f"{BASE_URL}/users/@me", headers=headers)
14response.raise_for_status()
15bot_user = response.json()
16print(f"Authenticated as: {bot_user['username']}#{bot_user['discriminator']}")

Key endpoints

1204 No Content (empty body)

1204 No Content (empty body)

1[{"id":"1234567890","name":"Member","color":3447003,"hoist":false,"position":2,"permissions":"0","managed":false,"mentionable":true},{"id":"0987654321","name":"Moderator","color":15158332,"hoist":true,"position":5,"permissions":"8","managed":false,"mentionable":false}]

Step-by-step automation

1curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
2  "https://discord.com/api/v10/guilds/$GUILD_ID/roles"

1curl -s -o /dev/null -w "%{http_code}" -X PUT \
2  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  "https://discord.com/api/v10/guilds/$GUILD_ID/members/$USER_ID/roles/$ROLE_ID"

1curl -s -o /dev/null -w "%{http_code}" -X DELETE \
2  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  "https://discord.com/api/v10/guilds/$GUILD_ID/members/$USER_ID/roles/$ROLE_ID"

1# Read rate limit headers from a role assignment
2curl -v -X PUT \
3  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
4  "https://discord.com/api/v10/guilds/$GUILD_ID/members/$USER_ID/roles/$ROLE_ID" \
5  2>&1 | grep -i 'x-ratelimit'

Complete working code

This script fetches all roles in the guild, accepts a list of (user_id, role_name) pairs, verifies hierarchy before each assignment, assigns or removes roles with rate-limit-aware backoff, and logs all actions. Run it as a standalone script or integrate the assign_role/remove_role functions into your bot's slash command handler.

1import os, time, random, logging, requests
2
3logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
4
5BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
6GUILD_ID = os.environ["DISCORD_GUILD_ID"]
7BASE = "https://discord.com/api/v10"
8HEADERS = {"Authorization": f"Bot {BOT_TOKEN}"}
9
10def get_roles():
11    resp = requests.get(f"{BASE}/guilds/{GUILD_ID}/roles", headers=HEADERS)
12    resp.raise_for_status()
13    return {r["name"]: r for r in resp.json()}
14
15def call_with_backoff(method, url, max_retries=5):
16    for attempt in range(max_retries):
17        resp = requests.request(method, url, headers=HEADERS)
18        if resp.status_code == 429:
19            wait = resp.json().get("retry_after", 1) + random.uniform(0, 0.5)
20            logging.warning(f"Rate limited, sleeping {wait:.2f}s")
21            time.sleep(wait)
22            continue
23        return resp
24    raise RuntimeError("Max retries exceeded")
25
26def assign_role(user_id, role_id):
27    url = f"{BASE}/guilds/{GUILD_ID}/members/{user_id}/roles/{role_id}"
28    resp = call_with_backoff("PUT", url)
29    if resp.status_code == 204:
30        logging.info(f"Assigned role {role_id} to user {user_id}")
31    elif resp.status_code == 403:
32        logging.error(f"403 on {user_id}: check bot role hierarchy")
33    else:
34        resp.raise_for_status()
35
36def remove_role(user_id, role_id):
37    url = f"{BASE}/guilds/{GUILD_ID}/members/{user_id}/roles/{role_id}"
38    resp = call_with_backoff("DELETE", url)
39    if resp.status_code == 204:
40        logging.info(f"Removed role {role_id} from user {user_id}")
41    else:
42        resp.raise_for_status()
43
44if __name__ == "__main__":
45    roles = get_roles()
46    logging.info(f"Loaded {len(roles)} roles")
47
48    # Example: assign "Member" role to a list of user IDs
49    member_role_id = roles["Member"]["id"]
50    user_ids = ["123456789012345678", "234567890123456789"]
51
52    for uid in user_ids:
53        assign_role(uid, member_role_id)
54        time.sleep(0.05)  # 50ms spacing for bulk ops
55

Error handling

Rate Limits for Discord API

1import time, random
2
3def rate_limited_request(method, url, headers, max_retries=5):
4    import requests as req
5    backoff = 1.0
6    for attempt in range(max_retries):
7        resp = req.request(method, url, headers=headers)
8        if resp.status_code != 429:
9            return resp
10        data = resp.json()
11        wait = data.get('retry_after', backoff) + random.uniform(0, 0.5)
12        time.sleep(wait)
13        backoff = min(backoff * 2, 64)
14    raise RuntimeError('Max retries exceeded')

• Read X-RateLimit-Remaining on every response and proactively slow down when it approaches 0.
• Add a 50ms fixed delay between calls in bulk loops — keeps you at 20 req/s, well under the 50 req/s global cap.
• Group role assignment events by bucket: the same route shares a bucket, so parallel requests to the same endpoint drain it faster than sequential ones.
• Never hard-code the X-RateLimit-Limit value — it can change without notice. Always read headers at runtime.
• Monitor for X-RateLimit-Global: true in 429 responses — this means all endpoints are blocked, not just the current route.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Always fetch roles with GET /guilds/{id}/roles at startup and cache the name-to-ID map — never hardcode role IDs, they change when roles are deleted and recreated.
• Check role hierarchy before every assignment attempt: if the target role position >= the bot's highest role position, skip and log a warning rather than hitting a 403.
• Use idempotent operations: calling PUT when a user already has the role is harmless — it's safer than checking first (which costs an extra API call).
• For bulk assignments, add a minimum 50ms delay between calls to stay under rate limit thresholds without complex backoff logic.
• Always check the HTTP status code before processing responses — Discord returns 204 (not 200) for successful role operations.
• Implement a dead-letter queue for failed role assignments so you can retry them after fixing the root cause (wrong hierarchy, member left, etc.).
• Test in a private test server before deploying to production — role hierarchy mistakes that look fine in testing can have different effects with different role orders.

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue