If you want to do some API requests on behalf of another user, you need to register an OAuth application.
For example, you might be creating a website that processes someone’s itch.io data in some way.
Or, you want to use the itch.io API in your game even when it’s launched without the itch.io app.
Tip: If you just want to use the itch.io API in your game, you can simply add the API scopes you need in your app manifest.
It’s by far the easiest for you to set up, and the best user experience for your players!
The API documented in this page implements the “Implicit flow” of the OAuth 2.0 spec. If you're already familiar with it, you should only need to skim through the page and pick the implementation details you need.
In short, the OAuth 2.0 implicit flows works like this:
hashpart of the URL.
As a developer, you can manage your OAuth applications from your user settings.
Try to keep things neat and tidy. If you have multiple websites or games using the itch.io API for a different purpose, create separate OAuth apps for them.
To let users choose to grant permissions to your apps, you should redirect them to the following address:
It requires the following parameters:
client_id: The Client ID corresponding to your OAuth application, which you can retrieve from your OAuth application settings
scope: A space-separated list of scopes you'd like access to (see the Scopes section below)
redirect_uri: The address of a page the user will be redirected to if they accept to grant your app permissions. This must match your OAuth application settings. See the Redirect URI section below.
state(optional): If this is specified, it will be included in the hash part of the address the user is redirected to. See the Security Considerations section below.
The parameters should be included as a query string. Here’s a sample authorization URL with dummy values:
The only scope you can request is
profile:me. It gives you access to the
/me API endpoint. In the future, as we expand the API, we will make more
scopes available. Need something specific? Get in touch.
See the server-side documentation for a list of endpoints and their scopes.
The redirect URI (or Authorization callback address) is where a user will get redirected after they approve your request for credentials.
The credentials are included in the hash part of the URL.
For example, if you specify the following redirect URL:
Then the user will get redirected to the following page:
The hash part of the URL is encoded like a query string – see the next section for retrieval.
If you're creating a desktop application, you may have to set the redirect URI
to the loopback address, like
If you set the redirect URI to
urn:ietf:wg:oauth:2.0:oob, the user won’t be
redirected. Instead they'll be shown a page with the API key and instructions
to copy and paste it into your app.
This is especially useful in scenarios where:
So, as a best practice, if you're implementing a desktop app, you should
try to listen on your registered loopback address, and if you can’t, fall back
urn:ietf:wg:oauth:2.0:oob and allow your user to copy & paste the API key instead.
The hash part of URLs is not seen by HTTP servers, or HTTP proxies. That’s why the OAuth 2.0 Implicit Flow puts sensitive information (the access token) in there.
It’s tempting to use a couple of regular expressions to retrieve the access token, but we encourage you to use libraries or standard APIs instead.
Here is example code to retrieve the access_token:
// this code assumes a recent browser or polyfill - see next paragraphs // first, remove the '#' from the hash part of the URL var queryString = window.location.hash.slice(1); var params = new URLSearchParams(queryString); var accessToken = params.get("access_token"); // you can also get the state param if you're using it: var state = params.get("state");
See this code in action in this codepen
URLSearchParams is available in recent browsers, see the ‘Browser compatibility’ section of URLSearchParams’s MDN page.
If you need to support older browsers, you can use a polyfill: url-search-params comes with a build you can easily include in your website.
Once you've successfully extracted the access token from the hash part of the URL, posted it to your server with an XHR, and saved it in your database, you can use it to make API requests.
Access tokens given by the OAuth 2.0 flow are API keys, which you can use as described in the server-side API docs.
You can use the
/credentials/info endpoint to list the scopes associated
with an access token. Look it up in the server-side API docs
To avoid various types of attack, the OAuth 2.0 spec recommends only requesting the scopes you need:
profile:me, don’t request all of
We only support the
profile:mescope right now, but as we expand the API you'll be able to request more scopes.
The OAuth Authorization callback page should be served over HTTPS to avoid man-in-the-middle attacks. Nowadays, getting an SSL certificate is easy thanks to efforts like Let’s Encrypt
The OAuth Authorization callback page should not include any third-party
make sure your access token extraction code runs first and that it clears
state parameter can be used as a nonce – it is generated by your server, included in the
login URL, and then again in the callback URL as part of the hash. You should check that the value
you get back is equal to the one you passed in.