Skip to main content
Every request to the Top.gg API requires authentication via a token. For your own project you obtain this token from the project’s dashboard settings and include it in the Authorization header of each request. The format differs between v0 and v1. Applications that act on behalf of other users authenticate with OAuth access tokens instead.
Keep your API token secret. Do not commit it to source control or expose it in client-side code. Use environment variables to manage it securely.

​
Get your API token

1

Open your project's dashboard

Navigate to your project’s page on Top.gg and open the dashboard. For v0, go directly to:
For v1, open the Integrations & API settings section of your project page.
2

Copy your token

Locate the API token displayed in the Integrations & API section and copy it. This is the token you will use to authenticate your requests.

​
Authenticate v1 requests

Pass your token as a Bearer token in the Authorization header:
For example, using curl:
Legacy tokens issued without the Bearer prefix do not work on v1 endpoints. If you are migrating from v0, create a new token from your project’s Integrations & API settings for use with v1.

​
Authenticate with OAuth access tokens

If your application works with projects owned by other users, let them authorize it through OAuth instead of asking for their project tokens. The access token you receive is passed the same way as a v1 project token, and the project is addressed by ID instead of @me:
Access tokens expire after seven days. Use the refresh token to get a new one. See authorization for the full flow.

​
Authenticate v0 requests

Pass your token directly in the Authorization header without the Bearer prefix:
For example, using curl:

​
Error responses

The v1 API returns errors in the RFC 7807 application/problem+json format. Every error response includes a structured body describing the problem:
A 401 Unauthorized response, for example, will include a type field identifying the error class, a human-readable title, the HTTP status code, and a detail message explaining the specific issue.