Before you can access any of the API endpoints, you need to create your app in our developer portal and obtain its API Token.
Please follow these steps to create an application:
- To access the developer portal, please visit the Dashboard.
- On the guild selection page, scroll all way down to the bottom and click Developer Portal.
- Click the blue New app button.
- Please enter your application's name and add a URL to your app's hosted logo. Both should be easily recognizable to your users to simplify subsequent authorization processes.
- Please select if the app should be private. Private apps can only be added to guilds by the owner of the app. Everyone can add public apps.
- Hit Save.
Congratulations, you created your first app in our system! An API token has been generated for you, and you can reveal or copy it by clicking the respective buttons in your app box.
To allow your application to access any data, it must, in any case, be authorized by each guild you want to access. If you want to perform actions on behalf of users, you need their authorization as well.
Let's have a look at both cases.
To access a guild and its users' data, it's required that the guild's administrators opt into that access. You can request this consent by forwarding a guild administrator to an Authorization Page, which looks very much like a simplified OAuth page.
To generate a link to this page for your app, please follow these steps:
- Click the button Create authorization link in your app box - this will spawn a small helper tool to create an authorization link for you.
- Leave the selector at the top on Guild.
- Choose the permissions your app needs to work. Do not request more permissions than you need to make a reputable impression to our users. If you need more permissions, you can later route the admins through the authorization page again. Don't be greedy.
- Copy the link at the bottom. You can use the same link for all guild authorization flows as the admins can select which server they want to authorize on the Authorization Page.
The Authorization Page will look like this and help our users understand what data your app can access and which actions it can perform. If they agree with your request, they only need to click the Authorize button, and your API token is immediately authorized to access the requested endpoints for that guild.
To act on behalf of a user, every user you want to do this must opt into these operations. The flow is extremely similar to authorizing a guild. Please follow the steps above again, but change the selector mentioned in step 2 to User. Then, you can again choose the required permissions and copy the link. That link will be the same for all users as they need to authenticate themselves with their Discord account beforehand.