Linked Roles Docs (#61)

Author: SCDerox

.github/workflows/check.yml

@@ -16,6 +16,8 @@ Hey there,
 
 The holidays are just around the corner! Easter is coming up, so it's time to prepare an event for your Discord – and it's super easy with SCNX!
 
+<!-- truncate -->
+
 ## Easter is Just Around the Corner
 
 Easter is just around the corner, and what could be better than going on an Easter egg hunt together – even if it's digital this year.

blog/13-04-2025-newsletter.md

@@ -0,0 +1,149 @@
+---
+description: Setting up Linked Roles might take a few minutes, but by following this guide, you can get started easily.
+---
+
+# Setup Linked Roles on your Discord
+
+Get started with Linked Roles on your Discord to improve your user experience by displaying important roles of users
+next to their names.
+
+:::success What is this?
+Unsure what Linked Roles are? Linked Roles allow you to display the role of a user next to their username, like this:
+
+![SCNX Linked Roles usage shown on a Discord server, the position of the user is displayed next to their username](https://scnx.app/img/linked-roles-example.png)
+
+If you want to learn more about Linked Roles, you can do so in our [About Linked Roles](./linked-roles/intro) section.
+
+:::
+
+:::warning This feature is Early Access
+Linked roles are Early Access. This means that in addition to a paid plan,
+a [membership](https://membership.scootkit.com) with Early Access is also required. Early Access helps us invest money &
+time in developing new features and products. We plan to make this feature available to everyone with Unlimited /
+Professional plan without memberships in late Q2 2025.
+:::
+
+<IncludedInPlan data={{PROFESSIONAL: true, UNLIMITED: true, STARTER: false}} additionalDetails={{
+UNLIMITED: "Additional Early Access subscription required during Beta trial. Beta will end in Q2 2025.",
+PROFESSIONAL: "Additional Early Access subscription required during Beta trial. Beta will end in Q2 2025."}} />
+
+## Video (German) {#video}
+
+Our developer Simon is happy to guide you through this setup process in
+our [tutorial video on YouTube](https://www.youtube.com/watch?v=HR3yvTVpkOI). This video is in German right now, but
+we're working on an English translation.
+
+<Video url="https://www.youtube.com/watch?v=HR3yvTVpkOI" />
+
+## 0. Pre-Flight-Checklist 🛫 {#step-0}
+
+Before you can enable Linked Roles on your server, please ensure that
+
+* you have [added your Server to SCNX](./setup).
+* your server has the paid [Unlimited](./scnx/guilds/plans) (<PlanPrice plan="UNLIMITED" type="MONTHLY"/>)
+  or [Professional](./scnx/guilds/plans) (<PlanPrice plan="PROFESSIONAL" type="MONTHLY"/>) plan, or consider using a
+  free trial, if
+  available for you.
+* you are the owner of the server you want to enable this feature
+  on ([why?](./scnx/guilds/trusted-admins#troubleshooting)) - if you are not the owner, please ask them to enable this
+  feature for you and grant you access as a [Trusted Admin](./scnx/guilds/trusted-admins).
+* you (or one of your trusted admins) have Early Access (purchasable with
+  a [ScootKit Membership Level 2 or higher](https://membership.scootkit.com)) during the beta trial. After the beta
+  trial ends (likely in Q2 2025), this requirement will be removed.
+* you've got 5-10 minutes of time (our estimate is that this takes around six minutes to finish on a computer, on mobile
+  it may take
+  a bit longer) to finish this guide - don't stop in the middle; your progress won't be saved.
+
+## 1. Time to get started {#step-1}
+
+To get started with the setup, please open the [Linked Roles page](https://scnx.app/glink?page=linked-roles/enable) of
+your server in the SCNX dashboard. There, click on "Start setup" to get started. You might be shown a video or a link to
+this guide, but you can also click "Continue" there, since you are already here :wink:
+
+## 2. Select credentials {#step-2}
+
+Next, SCNX will prompt you to select which Discord credentials you want to use for Linked Roles. If you are using other
+SCNX products, like [Modmail](./modmail/intro) or the [Custom Bot](./custom-bot/custom-commands), you can select them
+from this list and [skip to step 3](#step-3). If you are not using any other product, please
+follow [these instructions](#step-2-app).
+
+![SCNX prompting user to select credential source](@site/docs/assets/linked-roles/setup/select-credentials.png)
+
+### Creating a Discord bot application {#step-2-app}
+
+If you are not using the credentials of another product, you'll need to create a new app in your Discord Developer
+Dashboard.
+
+To do so, visit the [Discord Developer Portal](https://discord.com/developers/applications). There, create a new
+application by clicking on "New Application" on the upper-right side of your Developer Portal. A modal will open. Enter
+the name of the application (you can change this later), read & accept
+the [Discord Developer Terms of Service](https://discord.com/developers/docs/policies-and-agreements/terms-of-service)
+and the [Discord Developer Policy](https://discord.com/developers/docs/policies-and-agreements/developer-policy) (these
+policies also apply to your use of the Discord API as part of SCNX) and create your bot by confirming with "Create".
+
+![This screenshot shows how to create a new application in the Discord Developer Portal](@site/docs/assets/setup/custom-bot-1.png)
+
+Next, open the "Bot"-Settings in the navigation bar on the left-hand side.
+There, you can configure the avatar and username.
+
+The final step in the Developer Dashboard is to generate a token and copy it. To do so, open the "Bot" page of your
+application
+and click on "Reset token" (still on the Bot page) and confirm your request in the modal. You might get asked
+to enter a 2FA-Code for your Discord-Account.
+
+Once done, please **copy the token of your bot and enter it on SCNX**.
+
+![This screenshot shows how to generate and copy the Bot Secret](@site/docs/assets/setup/custom-bot-3.png)
+
+Once done, SCNX will check your token and synchronize data with Discord. Once done, you can continue
+with [the next step](#step-3).
+
+## 3. Save redirect URL {#step-3}
+
+Once your credentials are checked and SCNX has synchronized some Linked-Role data with Discord, you'll need to open the
+Oauth2 page of your Discord Developer Portal. The easiest way to do so is to click on the link that is visible on SCNX.
+Alternatively, you can click on "Oauth2" tab in your developer dashboard.
+
+![This screenshots shows how the user should click on "Open Oauth2 panel"](@site/docs/assets/linked-roles/setup/click-on-oauth2-page.png)
+
+Once you've opened the Oauth2 page, you'll need to copy and paste the redirect URL from your SCNX Dashboard. Doing this
+is easy: Simply click on the URL shown in SCNX (this will copy the URL to your clipboard). If you are wondering, the
+redirect URL should look something like this:
+`https://linked-roles.scnx.app/api/b4e5e89a-1c92-11f0-b688-03c2706e348f/callback` (the middle part might change based on
+your server).
+
+![This screenshots shows which value the user should copy from the dashboard](@site/docs/assets/linked-roles/setup/copy-redirect-url.png)
+
+Go back to the "Oauth2"-Page
+in your Discord Developer Portal. There, scroll to "Redirects", click on "Add another" and paste the URL you just copied
+in the text field. Remember to save your changes!
+
+![This screenshot shows where to paste the copied redirect URL](@site/docs/assets/linked-roles/setup/enter-redirect-url.webp)
+
+## 4. Enter Client Secret {#step-4}
+
+:::warning Confusion avoidance warning
+There's a big difference between your **Bot Token** and **Client Secret**. Please double-check which value you are
+entering to avoid issues later. For this step, you'll need the **Client Secret**, not the Bot Token.
+:::
+
+Once you've entered and saved the Redirect URL, please stay on the "Oauth2 page". Below "Client Information", generate
+the Client secret, by clicking on "Reset Secret" below the "Client Secret" field. Discord might ask you to verify your
+account by entering a 2FA code. Once this is done, you'll be able to copy the Client secret. Enter the copied value in your
+SCNX Dashboard and click on "Create Linked-Roles" to finish setup.
+
+![This screenshot shows how to copy the client secret](@site/docs/assets/linked-roles/setup/copy-client-secret.png)
+
+## 5. Time to party 🎉 {#step-5}
+
+:::info Don't worry
+Your new Linked Role Bot won't stay online unless you use another SCNX product with the same credentials.
+:::
+
+Finally, finish setup by inviting the Linked Roles Bot to your server. Do so by clicking "Invite Linked-Roles-Bot" in
+the dashboard. Once done, you can continue by creating your first Linked Role. To learn more about that, continue in
+our [Role management documentation](./linked-roles/role-management#create-linked-scnx-role), where we explain how to
+create your Linked Roles on SCNX and on Discord. You can also jump
+to [the Linked Roles index page](/docs/linked-roles/overview) if you are looking for something else to continue with.
+
+![This screenshot shows the success message after setup](@site/docs/assets/linked-roles/setup/success-party-time.png)

docs/assets/linked-roles/add-role.png

@@ -0,0 +1,76 @@
+---
+sidebar_position: 3
+description: Follow this guide to claim a Linked Role that has been assigned to you.
+---
+
+# How to claim a Linked Role
+
+Once you've been assigned a role, claiming it in Discord is easy! Follow this guide to claim your Linked Role.
+
+:::success Share me!
+You can share this guide with your members so they know how to get their roles!\
+Here's the URL to share: [`https://scootk.it/claim-linked-roles`](https://scootk.it/claim-linked-roles).
+:::
+
+## Requirements {#requirements}
+
+Before you can claim your Linked Role, an administrator needs to
+have [created the Linked Role on SCNX](./role-management#create-linked-scnx-role), [configure it on Discord](./role-management#linked-role-on-discord)
+and then [assign the role](./user-management#add-role) to you. If these steps aren't finished, you won't be able to claim
+your role.
+
+If you run into issues when following this guide, please contact your server administrator and link them to
+our [troubleshooting page](./troubleshooting), where we go into detail on how to fix issues.
+
+## Claim your role on Discord {#claim-role}
+
+:::info This also works on your phone!
+While this guide shows the steps on a desktop device, you can follow the same instructions on your phone to claim your
+Linked Role.
+:::
+
+To get started, please click on the name of the server in Discord. There you'll be able to select the option "Linked
+Roles". A modal showing all available roles will now appear. Select the role you want to claim. Next, you will be shown
+the requirements you need to pass to claim the role. If you already pass the requirement, you can click on "Finish",
+otherwise click on the requirement field to claim your role.
+
+![How to open the Linked Role claim site on Discord](@site/docs/assets/linked-roles/claim/1.png)
+
+Now, the [authorization page](./settings#authorization-page) of the server will open. There, click on "Authorize with
+Discord". You will be redirected to Discord to authorize your account. Please make sure you are logging in with the
+right account, then click on "Authorise" to finish the request. After that, you will be shown a success message
+confirming that the roles have been applied successfully. You can close this window now.
+
+![How to authorize your account](@site/docs/assets/linked-roles/claim/2.png)
+
+Once done, go back to Discord. There, you will be prompted to confirm the connection by clicking on "Done". After that,
+you can finally claim the Linked Role by clicking "Finish". Discord will grant you the Linked Role now, which will also
+appear in your member profile.
+
+![Final step to claim the role](@site/docs/assets/linked-roles/claim/3.png)
+
+If you want to claim other roles as well, you can do so easily by going following the same instructions - but you won't
+need to authenticate again, you can simply claim the role in Discord.
+
+## Issues when claiming roles? {#issues}
+
+If you are running into any issues when you are trying to claim a role, please check
+our [troubleshooting guide](./troubleshooting), in particular, the following issues might occur:
+
+* [Error message: "Invalid OAuth2 redirect_url"](./troubleshooting#oauth2-redirect-url).
+* [Error message: "No roles were assigned to you"](./troubleshooting#roles-missing)
+* [Error message: "Seems like the configuration by the server owner is wrong."](./troubleshooting#generic-api-error).
+
+If you run into other issues or have questions, check or [troubleshooting guide](./troubleshooting) or contact us
+on [scnx.app/help](https://scnx.app/help) - we're always happy to help!
+
+## Remove a claimed role {#remove-claimed-role}
+
+Annoyed by your Linked Role? You can either ask an administrator
+to [remove the Linked Role](./user-management#remove-role) or you can remove the role yourself.
+
+To do so, open Discord and open your profile on your server. There, hover over the Linked Role you want to remove. You
+will see an "X" on the left side. Click on it to remove your Linked Role. If you ever change your mind, you can
+always [re-claim your Linked Role](#claim-role) unless an administrator removes it from you.
+
+![How to remove a claimed role](@site/docs/assets/linked-roles/claim/remove-role.png)

docs/assets/linked-roles/authentification-page.jpg

@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+description: Linked Roles allow you to easily display the role of a user next to their username in your chat.
+---
+
+# About Linked Roles
+
+:::warning This feature is Early Access
+Linked roles are Early Access. This means that in addition to a paid plan,
+a [membership](https://membership.scootkit.com) with Early Access is also required. Early Access helps us invest money &
+time in developing new features and products. We plan to make this feature available to everyone with Unlimited /
+Professional plan without memberships in late Q2 2025.
+:::
+
+Linked Roles allow you to display the role of a user next to their name on your Discord server. To do this, the user
+needs to authorize with your Discord Bot and claim their role manually. Displaying the role next to the username makes
+your Discord appear professionally and increases the user experience on your Discord server; your users can see at a
+glance that they are talking to a staff member, to a moderator or to an admin.
+
+Here's how Linked-Roles could look on your server:
+
+![SCNX Linked Roles usage shown on a Discord server, the position of the user is displayed next to their username](https://scnx.app/img/linked-roles-example.png)
+
+## How it works {#how-it-works}
+
+To use Linked Roles, you'll need to first [set up Linked Roles](./../linked-roles) on your server. Once done, you
+can [create and configure Linked Roles](./role-management) on SCNX and Discord which can
+be [assigned to users](./user-management). Once a linked role has been assigned to a user, the user
+can [claim the role](./claim-roles) on Discord.
+
+In contrast to actual roles on Discord, Linked Roles can't be directly assigned to members, instead, members will need
+to manually [claim roles on Discord](./claim-roles). After a user has claimed a role, the
+role [can only be removed via the SCNX Dashboard](./user-management#remove-role).
+
+Linked Roles can be displayed in the chat next to the username
+by [configuring chat permissions](./role-management#display-in-chat). While a user can have multiple Linked Roles, only
+one can be displayed in a chat. Roles with a higher position on your Discord will be displayed with a higher priority.
+Having a Linked Role does not remove the role icon of another role.
+
+To [claim a Linked Role](./claim-roles), users will need to authorize their account with your custom Discord application
+using a
+[customizable authorization page](./settings#authorization-page). Once done, they'll be redirected back to Discord,
+where they can claim their role. Once authorized, future role changes can be claimed without the need of an additional
+authorization.
+
+## Linked Roles at SCNX {#scnx}
+
+SCNX makes it easy to set up and manage Linked Roles on your very own Discord - there's no coding required and setup can
+be done in a few easy steps in our easy-to-use dashboard.
+
+To use Linked Roles, you need to [add your server to SCNX](./../setup) and have a [paid plan](../scnx/guilds/plans) that
+includes access to this feature - you can also try a paid plan for free if you are eligible.
+
+### Features of Linked Roles on SCNX {#scnx-features}
+
+Linked Roles on SCNX makes using Linked Roles on your server easy. While [initial setup](./../linked-roles) takes a few
+minutes, later management of [roles](./role-management) and [member roles](./user-management) is straightforward.
+Additionally, SCNX
+offers multiple features and customizability options.
+
+The following features are available on SCNX:
+
+* Easy management of [Linked Roles](./role-management) in the SCNX Dashboard.
+* [Assign and remove](./user-management) roles from users.
+* Multiple themes available for the [authorization page](./settings#authorization-page).
+* Off-Brand options available with the [Professional Plan](./../scnx/guilds/plans).
+* Authorization with your custom Discord App.
+* You can set up [public linked roles](./role-management#public-roles) that can be claimed by any user.
+* Excellent customer support on [our Discord](https://scootk.it/dc-en) in English and German.