Access Top.gg Projects on Behalf of Users with OAuth

OAuth lets your application act on behalf of a Top.gg user instead of using the project’s own API token. A user authorizes your application for one of their projects, and your backend receives tokens for that project. Each project the user grants gets its own authorization and its own tokens. Use OAuth when you build something for other people’s projects, for example a dashboard, a hosting panel, or a bot management tool. Keep using a project token when you only automate your own project.

​

How it works

1. You register an application and get a client ID and client secret.
2. Your application sends the user to the Top.gg authorization page with the scopes it needs.
3. The user signs in, selects one of their projects, and approves.
4. Top.gg redirects back to you with a code. You exchange it for an access token and a refresh token.
5. You call the v1 API with the access token. Refresh it when it expires.

The full flow with every parameter is on the authorization page.

​

What you can access

Access tokens work with the same v1 API as project tokens. Address endpoints by project ID. Project tokens use @me instead: Each endpoint requires a scope the user granted. On top of the project endpoints, OAuth tokens can call:

• GET /projects to look up the project the authorization covers
• GET /users/@me to identify the user who authorized you
• /users/@me/projects to list the user’s projects and create drafts for them
• Project webhooks to create and manage vote webhooks
• Project integrations to connect and disconnect integrations

​

Your application only manages what it created

Webhooks and integrations are shared between the project owner, the dashboard, and every application the owner authorized. To keep applications from interfering with each other, your application only sees and manages the webhooks it created and the integrations it connected. Everything else on the project is invisible to it, even with the matching scope.

​

Tokens

Revoking a refresh token revokes the whole authorization. The user can also remove your application from their Top.gg settings at any time, which invalidates all tokens immediately. If your application only acts on projects, the application token saves you from storing access tokens entirely: users authorize their projects once, and the single static token covers all of them. Access tokens remain necessary for the user.* scopes.