Quickstart

Register Your Client

If you haven't done so already, you'll first need to create an application.

1. Go to Special:SOA2Apps.
2. If prompted to login, do so and follow the instructions.
3. Click the link that says "New application".
4. Fill in a name for your application (or you can leave it blank, though make this temporary).
5. Enter your redirect URIs, putting one on each line.
   • Your user will be redirected to one of these URIs (chosen by you) after confirming that they want to authorize your application.
   • If you don't have a webserver or otherwise can't handle this type of flow, you can leave the redirect URIs field blank. Your user will be redirected to a builtin page that directly displays the code to them, which they can paste into your application somehow.
6. Click the button that says "Create".
7. Click the link that you are directed to.
8. Find your client ID and client secret. Show the secret for as long as you need to copy it. Configure your application with these values.
9. You can already test your application at this point. However, wait until your application's name has been moderated before releasing it. You'll know when it's moderated when the "Name moderated and approved?" field says "Yes".

If, for whatever reason, you need a programmatic way of doing this, there are also API endpoints for this purpose. Keep in mind that they ultimately still require a manual Scratch verification.

Authorization (The Thing You're Here For)

Let's say you need to verify the Scratch identity of one of your users.

1. Make sure you have a client ID and secret. (Click "Expand" to see that process.)
2. Construct an authorization URL with the following format:

   https://oauth2.scratch-wiki.info/wiki/Special:ScratchOAuth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scopes={scopes}&state={state}

   • {client_id} — your application's client ID
   • {redirect_uri} — one of the redirect URIs already registered to your application. If you have none, leave out this parameter (but note that your flow will be less secure)
   • {scopes} — scopes your application is requesting, separated by (URL-encoded) spaces
   • {state} — an arbitrary string that must be controlled by you
3. Direct your user to this URL.
4. After they confirm authorization, they will be redirected to your redirect URI with two query parameters added:
   • code — token-getter code, to be used next
   • state — the arbitrary string you included - verify that this matches what you set in your authorization URL, and make sure to fail on your end if it does not

   If you have no redirect URIs, your user will be redirected to a builtin page that directly displays the code. You can then prompt them to copy it from there and paste it into your application. This bypasses the state verification and is therefore less secure, so it is recommended to properly use redirect URIs.

5. Make a POST request to https://oauth2.scratch-wiki.info/w/rest.php/soa2/v0/tokens with the following information in the JSON-encoded body:
   • client_id — the client ID you obtained during registration
   • client_secret — the client secret obtained likewise
   • code — the token-getter code you just received
   • scopes — the scopes you put in your authorization URL
6. If successful, you will receive a JSON-encoded response containing, among other things (see the API reference), your access token for your user.
7. Base64-encode this token.
8. Make a GET request to https://oauth2.scratch-wiki.info/w/rest.php/soa2/v0/user with the HTTP header Authorization: set to Bearer <your base64-encoded token>
9. You will receive a JSON-encoded response containing the Scratch user name of your user.

You have successfully verified the Scratch identity of a user!