Linked Roles (role connection metadata)

Status Stable · Last verified 2026-07-11 · API v10 · Sources Role connection metadata, Update user role connection

Linked Roles let a server grant a role based on data your app verifies about a user (e.g. “account level ≥ 10”, “is a verified customer”). Your app publishes metadata records (the criteria) and sets each user’s values; Discord does the gating.

How it works

1. Your app registers up to 5 METADATA RECORDS (named numeric/date/boolean criteria).
2. Your app sets a "Linked Roles Verification URL" in the Developer Portal.
3. A user authorizes your app with the role_connections.write scope.
4. Your app PUTs that user's VALUES to their role connection.
5. A server admin creates a role requiring a criterion (e.g. level >= 10);
   Discord enforces it against the user's stored values.

Metadata records

Each record describes one comparison Discord can make. Verified fields:

Field	Rule
type	A comparison type (values below)
key	a-z, 0-9, _; 1–50 chars; unique within the app
name	1–100 chars (name_localizations optional)
description	1–200 chars (description_localizations optional)

Verified comparison types:

Type	Value
INTEGER_LESS_THAN_OR_EQUAL	1
INTEGER_GREATER_THAN_OR_EQUAL	2
INTEGER_EQUAL	3
INTEGER_NOT_EQUAL	4
DATETIME_LESS_THAN_OR_EQUAL	5
DATETIME_GREATER_THAN_OR_EQUAL	6
BOOLEAN_EQUAL	7
BOOLEAN_NOT_EQUAL	8

[!NOTE] Verified — max 5 records “An application can have a maximum of 5 metadata records.” Source: Role connection metadata.

Register the records (application / bot auth)

GET  /applications/{application.id}/role-connections/metadata
PUT  /applications/{application.id}/role-connections/metadata      # overwrites the set

PUT an array of record objects, authenticated as the application (bot token).

Setting a user’s values

After the user authorizes with role_connections.write, push their values with their Bearer token:

PUT /users/@me/applications/{application.id}/role-connection
Authorization: Bearer <user access token>
Content-Type: application/json

{
  "platform_name": "Example",        // optional, max 50 chars
  "platform_username": "user#1",     // optional, max 100 chars
  "metadata": { "level": "42" }      // values are STRINGS, max 100 chars each; keys match your records
}

GET /users/@me/applications/{application.id}/role-connection reads the current values (also role_connections.write).

[!CAUTION] Values are stringified The metadata object maps your record keys to stringified values (max 100 chars each) — even integers and booleans are sent as strings ("42", "true"). Discord parses them per the record’s type.

Runnable example

oauth2-linked-roles provides a validated metadata builder and both API calls (bot-auth register + Bearer user update) with mocked-fetch unit tests — no secrets needed to run the tests. Getting a user token with role_connections.write uses the authorization-code flow.

Security notes

• The bot token (registering records) and the user access token (setting values) are secrets — store server-side, never commit, rotate if leaked.
• Only request role_connections.write when you actually verify something.
• Validate values against your record types before sending (the example does).

Next

• Scopes — where role_connections.write sits.
• Authorization-code flow — obtaining the user token.