How to Use Discord Role Connections With OAuth2 Linked Accounts

Discord Role Connections let server members link their external accounts such as YouTube, Twitter, or Steam to their Discord profile. Once linked, you can assign server roles automatically based on those linked accounts using OAuth2. This feature helps you verify a member’s identity or grant access to exclusive channels based on their external account status. In this article, you will learn how to set up a Discord application, configure OAuth2 scopes for role connections, and create role assignment logic that works with your server’s roles.

What Are Discord Role Connections and How OAuth2 Links Accounts

Discord Role Connections allow a user to link an external account such as a YouTube channel, Twitter handle, or Steam profile directly to their Discord profile. When the link is established, the user’s Discord profile displays a small badge showing the linked account. Server owners can then create roles that are automatically assigned based on the metadata from that linked account. For example, you could assign a role called “YouTube Subscriber” to any member who links a YouTube channel with at least 100 subscribers.

The OAuth2 flow is the mechanism that makes this possible. Your Discord application requests permission from the user to read their external account data and write role connection metadata. The user authorizes your app, and your app then sets a metadata object on the user’s Discord profile. Discord’s servers check this metadata against the role assignment rules you configure in your server. If the metadata matches the conditions you defined, the role is automatically granted or revoked.

Prerequisites for Using Role Connections

Before you start, you need the following:

• A Discord server where you have the Manage Server permission.
• A Discord application created in the Discord Developer Portal.
• Access to the external platform’s API (for example, YouTube Data API or Twitter API v2) to fetch the user’s account data.
• A backend server capable of handling OAuth2 redirects and making HTTP requests to Discord’s API.

Steps to Set Up Discord Role Connections with OAuth2

The process involves four main stages: configuring your Discord application, building the OAuth2 authorization URL, handling the callback to fetch the external account data, and updating the role connection metadata. Follow these steps in order.

1. Create or select your Discord application in the Developer Portal
   Go to the Discord Developer Portal and click New Application. Give your application a name and click Create. If you already have an app, select it from the list.
2. Enable role connections and add the required OAuth2 scopes
   In your application settings, click OAuth2 in the left sidebar. Under Scopes, select role_connections.write. This scope allows your app to write role connection metadata to the user’s profile. Also add the appropriate scopes for the external platform: for YouTube, add youtube.readonly; for Twitter, add tweet.read and users.read. Click Save Changes.
3. Build the OAuth2 authorization URL
   Use the following template to construct the URL that users will click to link their account. Replace YOUR_CLIENT_ID with your app’s client ID and YOUR_REDIRECT_URI with the URL where users will be sent after authorization.
   https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=role_connections.write%20identify
   You must include the identify scope to read the user’s Discord ID. If you need data from the external platform, add its scope to the URL as well, separated by %20.
4. Handle the OAuth2 callback and exchange the code for an access token
   When the user authorizes your app, Discord redirects them to your redirect URI with a code query parameter. Your backend server must exchange this code for an access token by making a POST request to https://discord.com/api/oauth2/token with the following parameters:
   client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=THE_CODE&redirect_uri=YOUR_REDIRECT_URI
   The response contains an access_token that you will use for subsequent API calls.
5. Fetch the user’s external account data
   Use the access token to call the external platform’s API. For example, to get the user’s YouTube channel data, call https://www.googleapis.com/youtube/v3/channels?part=statistics&mine=true with the token in the Authorization header. Extract the relevant metadata such as subscriber count or channel name.
6. Update the role connection metadata on Discord
   Make a PUT request to https://discord.com/api/v10/users/@me/applications/YOUR_APPLICATION_ID/role-connection. Include the Authorization: Bearer ACCESS_TOKEN header. The request body is a JSON object where the metadata field contains key-value pairs that you define. Example body:
   {"platform_name": "YouTube", "metadata": {"subscriber_count": "150", "channel_name": "MyChannel"}}
   The keys you use in the metadata object must match the names you will later use in your server’s role assignment configuration.
7. Configure role assignment in your Discord server
   Open your Discord server and go to Server Settings > Roles. Create a new role or edit an existing one. Under Role Connections, click Add Requirement. Select the platform you linked (for example, YouTube) and define the condition. For instance, set Subscriber Count to greater than or equal to 100. Discord will automatically assign this role to any member whose role connection metadata meets the condition.
8. Test the flow with a user account
   Use a test Discord account that is not the server owner. Have that user click the OAuth2 authorization URL you built. After they authorize, check their Discord profile to confirm the linked account badge appears. Then verify that the role is automatically assigned in the server.

Common Mistakes and Limitations When Using Role Connections

Role is not assigned after the user links their account

The most common reason is that the metadata you wrote to Discord does not match the condition you set in the role requirement. Double-check the exact key names and data types. For example, if you wrote "subscriber_count": "150" as a string but the role requirement expects an integer, the comparison may fail. Use the correct data type as defined by the platform’s API.

OAuth2 authorization fails with an invalid scope error

This happens when you request a scope that your application has not been granted in the Developer Portal. Verify that you added the role_connections.write scope and any external platform scopes under OAuth2 > Scopes in your application settings. Also confirm that your redirect URI is exactly the same as the one registered in the portal.

Role connection metadata is not persisted after the user logs out

The role connection metadata you write is tied to the user’s Discord profile and persists until you delete it or the user revokes the authorization. If the data disappears, your backend may not be storing the access token securely. You need to store the user’s refresh token and use it to obtain a new access token when the old one expires. Discord’s OAuth2 tokens for role connections have a longer lifetime, but you should still implement token refresh logic.

You cannot assign roles based on metadata from multiple platforms in one condition

Each role requirement can only check metadata from a single platform. To require both a YouTube subscription and a Twitter follow, you would need to create two separate roles. Alternatively, you can write metadata from both platforms into a single role connection object, but Discord only evaluates conditions for the platform you select in the requirement dropdown.

Item	OAuth2 with Role Connections	Manual Role Assignment
Setup complexity	Requires a backend server and Developer Portal configuration	No coding needed, only server settings
Automation	Roles are assigned instantly after authorization	Roles must be assigned manually by an admin
Verification	Uses real external account data from the platform API	Relies on the admin’s judgment or manual checks
Scalability	Works for hundreds of users without additional work	Becomes time-consuming as the server grows

Now you can set up Discord Role Connections with OAuth2 to automatically assign roles based on linked external accounts. Start by creating your application in the Developer Portal and building the authorization URL. After you have the flow working, test with a few users to ensure the metadata conditions match your role requirements. For advanced use, consider storing the user’s refresh token in a database so you can update their role connection metadata periodically without requiring re-authorization.