OAUTH.md

OAuth2

The main Pokemon Showdown loginserver is fully equipped to serve as an OAuth2 provider. To make use of this functionality, you only need a client_id and a server able to handle the redirect.

Getting a client ID is as simple as filling out this form. We will try to get back to you as quickly as possible.

Functionality documentation

The root URL for these APIs is https://play.pokemonshowdown.com/api.

/oauth/authorize - Serves the front-end page for users to authorize an application to use their account. You must provide client_id, redirect_uri, and challenge in the querystrying. Once the user clicks the button to authorize the use, it will redirect them to the redirect_uri with an assertion and token in the new querystring. The assertion can be used for an immediate login, and you can store the token in a user's browser to get assertions without opening the page on future logins.

/oauth/api/getassertion - Requires challenge, client_id, and token parameters. This endpoint allows you to get a new assertion for a user without opening the authorize page. The challenge parameter is the challstr provided by the Pokemon Showdown server on login, and the token can be acquired from /oauth/authorize.

/oauth/api/refreshtoken - Requires client_id and token parameters. This endpoint allows you to refresh an expiring token (which happens after two weeks) without having to make the end user open /oauth/authorize again. You provide the old token, the server verifies it, invalidates the old one, and provides a new one for another two weeks of use.

Examples

Here's a simple functionality example for getting a token for a user.

const authorizeUrl = new URL('https://play.pokemonshowdown.com/api/oauth/authorize');
authorizeUrl.searchParams.append('redirect_uri', 'https://mysite.com/oauth-demo');
authorizeUrl.searchParams.append('client_id', clientId);
authorizeUrl.searchParams.append('challenge', challenge);

const popup = window.open(authorizeUrl, undefined, 'popup=1');
const checkIfUpdated = () => {
   try {
      if (popup?.location?.href?.startsWith(redirectUri)) {
         const url = new URL(popup.location.href);
         const assertion = url.searchParams.get('assertion');
         if (!assertion) {
            console.error('Received no assertion');
            return;
         }

         runLoginWithAssertion(url.searchParams.get('assertion'));

         const token = url.searchParams.get('token');
         if (!token) {
            console.error('Received no token')
            return;
         }

         localStorage.setItem('ps-token', token);
         popup.close();
      } else {
         setTimeout(checkIfUpdated, 500);
      }
   } catch (DOMException) {
      setTimeout(checkIfUpdated, 500);
   }
};

checkIfUpdated();

This opens the OAuth authorization page in a new window, waits for the user to click the button in the new window, then once the window's URL has changed, extracts the assertion and token from the new querystring, caches the token, and uses the assertion to log in.