ToolrinthLib OAuth2 Guide

In this guide, you’ll learn how to use the ToolrinthLib OAuth2 client to authorize users with Modrinth’s API.

Packages in this Guide

Express v5.2.1

for the web server

@toolrinth/lib v1.1.0

for Modrinth OAuth

This guide does not cover token storage methods (cookies, localStorage, etc). It also does not cover security measures, such as state. It is expected that you know how to handle the data you receive. This guide is focused on the nuances of the ToolrinthLib OAuth2 client.

---

1. Create a Modrinth OAuth Application

   To interact with Modrinth’s OAuth API, you need to create an application in your user application settings
2. Create a ToolrinthLib Project

   Create a barebones NPM project, and install the following packages:

   • express
   • @toolrinth/lib

   npm install express @toolrinth/lib
   

   Create the entrypoint file:

   touch index.js
   
3. Set up the Project

   First things first, we need to create our Express server and the ToolrinthLib OAuth2 client. We also need to listen for GET requests on the root path (/)

   Show Code

   index.js

   import express from "express";
   import { OAuth2 } from "@toolrinth/lib";
   
   const PORT = 3000;
   
   // Replace with the Client ID and Client Secret of your Modrinth application
   const CLIENT_ID = "...your client ID";
   const CLIENT_SECRET = "...your client secret";
   
   // Request all of the scopes we added to the Modrinth application
   const SCOPES = [
     OAuth2.Scopes.USER_READ,
     OAuth2.Scopes.PROJECT_READ,
     OAuth2.Scopes.VERSION_READ,
     OAuth2.Scopes.ORGANIZATION_READ,
   ];
   
   // Create the Express Webserver
   const app = express();
   
   // Create the ToolrinthLib OAuth2 Client
   const oauth2 = new OAuth2.Client(
     CLIENT_ID,
     CLIENT_SECRET,
     "http://localhost:3000",
     SCOPES
   );
   
   // Listen for GET requests on http://localhost:3000/
   app.get("/", async (request, response) => {
   
     // Respond to the client. We will replace this soon.
     response.send("Hello World!");
   
   });
   
   // Start Express on port 3000
   app.listen(PORT);
   
   

   Start the webserver with node index.js

4. Listen for Requests

   Now that our webserver is online, we need to check whether or not incoming requests contain an authorization code, and act accordingly.

   Show Code

   index.js

   ...
   
   
   // Listen for GET requests on http://localhost:3000/
   app.get("/", async (request, response) => {
   
     // Authorization codes are passed as the "code" query parameter
     const code = req.query?.code || null;
   
     if (!code) {
   
       // If there is no code, we need to redirect the user to Modrinth to authorize.
       //
       // getRedirectUrl() provides a "state" value, which should be used to ensure security when authenticating users.
       const urlResponse = oauth2.getRedirectUrl();
   
       // Redirect the user to Modrinth to authorize
       response.redirect(urlResponse.redirect_url);
   
     } else {
   
       // The user has been through Modrinth authentication.
       //
       // Soon, we'll swap the authorization code for an access token to use with Modrinth's API
   
     }
   
   });
   
   ...
   
   
5. Obtain an Access Token

   One you have an authorization code, you can use OAuth2.Client#exchangeCode() to obtain an access token for use with the Modrinth API.

   Show Code

   index.js

   ...
   
   
   } else {
   
     // Exchange the authorization code for an access token
     const { data, error } = await oauth2.exchangeCode(code);
   
     if (error) return response.sendStatus(error.status);
   
     response.send(`Your token is: ${data.access_token}`); // Do not do this (duh)
   
   }
   
   ...