Authentication

The Modrinth API supports two authentication methods: Personal Access Tokens (PATs) and OAuth 2.0. Most endpoints are public and don’t require authentication, but certain operations require an authenticated request.

When Authentication is Required

Authentication is needed for:

Creating data - Creating projects, versions, reports, etc.
Modifying data - Editing project metadata, updating versions, etc.
Accessing private data - Draft projects, notifications, emails, payout data
User-specific operations - Managing collections, following projects, etc.

Most read operations (viewing public projects, searching, downloading files) do not require authentication.

Personal Access Tokens

Personal Access Tokens (PATs) are the recommended authentication method for server-side applications and scripts.

Creating a PAT

Log in to modrinth.com
Navigate to Settings > Account
Scroll to the Personal Access Tokens section
Click Create a token
Enter a token name and select the required scopes
Click Create and copy your token immediately

Your token is only shown once during creation. Store it securely - treat it like a password.

Using a PAT

Include your token in the Authorization header:

curl -X GET "https://api.modrinth.com/v2/user" \
  -H "Authorization: mrp_RNtLRSPmGj2pd1v1ubi52nX7TJJM9sznrmwhAuj511oe4t1jAqAQ3D6Wc8Ic"

const response = await fetch('https://api.modrinth.com/v2/user', {
  headers: {
    'Authorization': 'mrp_YOUR_TOKEN_HERE',
    'User-Agent': 'my-app/1.0.0'
  }
});

Token Format

PATs always start with the prefix mrp_ (Modrinth Personal Token):

mrp_RNtLRSPmGj2pd1v1ubi52nX7TJJM9sznrmwhAuj511oe4t1jAqAQ3D6Wc8Ic

Managing PATs

You can manage your tokens at any time:

View tokens: See all active tokens and their last used date
Revoke tokens: Immediately invalidate a token
Update scopes: Create a new token with different permissions

OAuth 2.0

OAuth 2.0 is the recommended method for client-side applications that act on behalf of users.

OAuth Flow Overview

Create an OAuth Application in your Modrinth account settings
Redirect users to Modrinth’s authorization page
Receive authorization code via callback
Exchange code for access token
Make authenticated requests using the access token

Creating an OAuth Application

Navigate to Settings > Applications
Click Create an application
Fill in:
- Name: Your application name
- Description: What your app does
- Redirect URIs: Allowed callback URLs (one per line)
- Max Scopes: Maximum permissions your app can request
Click Create and note your Client ID and Client Secret

Step 1: Initiate Authorization

Redirect users to Modrinth’s authorization endpoint:

https://api.modrinth.com/v2/_internal/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=USER_READ+PROJECT_READ+PROJECT_WRITE&
  state=random_state_string

Parameters:

client_id (required): Your OAuth application’s client ID
redirect_uri (required): Must match a registered redirect URI
scope (optional): Space or + separated list of scopes (defaults to app’s max scopes)
state (recommended): Random string to prevent CSRF attacks

Step 2: Handle the Callback

After the user authorizes your app, they’re redirected to your callback URL:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=random_state_string

Or if the user denies access:

https://yourapp.com/callback?error=access_denied&state=random_state_string

Step 3: Exchange Code for Token

Exchange the authorization code for an access token:

curl -X POST "https://api.modrinth.com/v2/_internal/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"

Response:

{
  "access_token": "mro_xxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "USER_READ PROJECT_READ PROJECT_WRITE"
}

Step 4: Use the Access Token

Use the access token in the Authorization header:

curl -X GET "https://api.modrinth.com/v2/user" \
  -H "Authorization: mro_xxxxxxxxxxxx"

OAuth access tokens start with the prefix mro_ (Modrinth OAuth).

Token Refresh

OAuth tokens expire after a period of time. When a token expires, you’ll receive a 401 Unauthorized response. Users must re-authorize to obtain a new token.

Scopes and Permissions

Both PATs and OAuth tokens use scopes to limit permissions. Request only the scopes your application needs.

Available Scopes

User Scopes

USER_READ: Read user profile data
USER_READ_EMAIL: Read user email address
USER_WRITE: Update user profile (username, avatar, bio, etc.)
USER_DELETE: Delete user account (PAT only, not available via OAuth)
USER_AUTH_WRITE: Modify authentication settings (PAT only)

Project Scopes

PROJECT_CREATE: Create new projects
PROJECT_READ: Read user’s projects (including private/draft)
PROJECT_WRITE: Edit project metadata, team members, settings
PROJECT_DELETE: Delete projects

Version Scopes

VERSION_CREATE: Upload new versions
VERSION_READ: Read user’s versions (including private/draft)
VERSION_WRITE: Edit version metadata and files
VERSION_DELETE: Delete versions

Notification Scopes

NOTIFICATION_READ: Read user notifications
NOTIFICATION_WRITE: Mark notifications as read or delete them

Collection Scopes

COLLECTION_CREATE: Create collections
COLLECTION_READ: Read user’s collections (including private)
COLLECTION_WRITE: Edit collections
COLLECTION_DELETE: Delete collections

Analytics & Payouts

ANALYTICS: Access analytics data
PAYOUTS_READ: Read payout information
PAYOUTS_WRITE: Withdraw funds
PERFORM_ANALYTICS: Submit analytics events

Other Scopes

REPORT_CREATE: Create reports
REPORT_READ: Read user’s reports
THREAD_READ: Read message threads
THREAD_WRITE: Send messages in threads
ORGANIZATION_CREATE: Create organizations
ORGANIZATION_READ: Read user’s organizations
ORGANIZATION_WRITE: Edit organizations

Scope Format

In OAuth URLs, separate scopes with spaces or +:

scope=USER_READ+PROJECT_READ+VERSION_CREATE

When creating PATs, select scopes from the web interface.

Restricted Scopes

Some scopes are restricted and cannot be used in PATs:

USER_DELETE
USER_AUTH_WRITE
PAT_CREATE, PAT_READ, PAT_WRITE, PAT_DELETE
SESSION_READ, SESSION_DELETE, SESSION_ACCESS

These operations can only be performed through Modrinth’s frontend for security reasons.

Token Security Best Practices

Never expose tokens in client-side code, public repositories, or logs.

Storage

Server-side: Store in environment variables or secure credential management systems
Client-side: Store OAuth tokens in secure, HttpOnly cookies or encrypted storage
Never commit tokens to version control

Transmission

Always use HTTPS for API requests
Never send tokens in URL parameters
Only send tokens in the Authorization header

Rotation

Rotate PATs periodically
Revoke tokens immediately if compromised
Use separate tokens for different applications
Set appropriate expiration times

Principle of Least Privilege

Request only the scopes your application needs
Create separate tokens for different use cases
Use read-only scopes when possible

GitHub Token Compatibility (Deprecated)

GitHub tokens are deprecated and will cease to function when API v3 becomes generally available. Migrate to PATs or OAuth immediately.

For backwards compatibility, some GitHub tokens still work with Modrinth’s API, granting all scopes. This is strongly discouraged for security and reliability.

Authentication Errors

401 Unauthorized

Your request lacks valid authentication credentials:

{
  "error": "unauthorized",
  "description": "Invalid authentication credentials"
}

Common causes:

Missing Authorization header
Invalid or expired token
Revoked token

403 Forbidden

Your token is valid but lacks the required scope:

{
  "error": "unauthorized",
  "description": "Token does not have the required scope: PROJECT_WRITE"
}

Solution: Create a new token with the required scopes.

Example: Complete OAuth Implementation

// Step 1: Redirect to authorization
function initiateOAuth() {
  const clientId = 'YOUR_CLIENT_ID';
  const redirectUri = 'https://yourapp.com/callback';
  const scope = 'USER_READ PROJECT_READ';
  const state = crypto.randomUUID();
  
  // Store state to verify later
  sessionStorage.setItem('oauth_state', state);
  
  const authUrl = `https://api.modrinth.com/v2/_internal/oauth/authorize?` +
    `client_id=${clientId}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `scope=${encodeURIComponent(scope)}&` +
    `state=${state}`;
  
  window.location.href = authUrl;
}

// Step 2: Handle callback
async function handleCallback() {
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const state = params.get('state');
  
  // Verify state
  if (state !== sessionStorage.getItem('oauth_state')) {
    throw new Error('Invalid state parameter');
  }
  
  // Exchange code for token (do this server-side!)
  const response = await fetch('https://api.modrinth.com/v2/_internal/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      code: code,
      redirect_uri: 'https://yourapp.com/callback'
    })
  });
  
  const { access_token } = await response.json();
  return access_token;
}

// Step 3: Make authenticated requests
async function getUser(accessToken) {
  const response = await fetch('https://api.modrinth.com/v2/user', {
    headers: {
      'Authorization': accessToken,
      'User-Agent': 'my-app/1.0.0'
    }
  });
  
  return await response.json();
}

Rate Limits

Learn about request limits and headers

Error Handling

Handle authentication and authorization errors

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

When Authentication is Required

Personal Access Tokens

Creating a PAT

Using a PAT

Token Format

Managing PATs

OAuth 2.0

OAuth Flow Overview

Creating an OAuth Application

Step 1: Initiate Authorization

Step 2: Handle the Callback

Step 3: Exchange Code for Token

Step 4: Use the Access Token

Token Refresh

Scopes and Permissions

Available Scopes

Scope Format

Restricted Scopes

Token Security Best Practices

Storage

Transmission

Rotation

Principle of Least Privilege

GitHub Token Compatibility (Deprecated)

Authentication Errors

401 Unauthorized

403 Forbidden

Example: Complete OAuth Implementation

Further Reading

Rate Limits

Error Handling

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

​When Authentication is Required

​Personal Access Tokens

​Creating a PAT

​Using a PAT

​Token Format

​Managing PATs

​OAuth 2.0

​OAuth Flow Overview

​Creating an OAuth Application

​Step 1: Initiate Authorization

​Step 2: Handle the Callback

​Step 3: Exchange Code for Token

​Step 4: Use the Access Token

​Token Refresh

​Scopes and Permissions

​Available Scopes

​Scope Format

​Restricted Scopes

​Token Security Best Practices

​Storage

​Transmission

​Rotation

​Principle of Least Privilege

​GitHub Token Compatibility (Deprecated)

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Example: Complete OAuth Implementation

​Further Reading

Rate Limits

Error Handling

When Authentication is Required

Personal Access Tokens

Creating a PAT

Using a PAT

Token Format

Managing PATs

OAuth 2.0

OAuth Flow Overview

Creating an OAuth Application

Step 1: Initiate Authorization

Step 2: Handle the Callback

Step 3: Exchange Code for Token

Step 4: Use the Access Token

Token Refresh

Scopes and Permissions

Available Scopes

Scope Format

Restricted Scopes

Token Security Best Practices

Storage

Transmission

Rotation

Principle of Least Privilege

GitHub Token Compatibility (Deprecated)

Authentication Errors

401 Unauthorized

403 Forbidden

Example: Complete OAuth Implementation

Further Reading