Overview

MangaDB supports OAuth 2.0 login and account linking for three providers: Google, Discord, and GitHub. Users can sign in with a provider (auto-registering on first use) or link a provider to an existing account.

All OAuth routes are prefixed with /auth/oauth.

All OAuth endpoints share a rate limiter: 20 requests per 15 minutes per IP.

Provider Setup

OAuth requires a Client ID and Client Secret for each provider, stored as environment variables in the backend .env file:

OAUTH_GOOGLE_CLIENT_ID=
OAUTH_GOOGLE_CLIENT_SECRET=
OAUTH_DISCORD_CLIENT_ID=
OAUTH_DISCORD_CLIENT_SECRET=
OAUTH_GITHUB_CLIENT_ID=
OAUTH_GITHUB_CLIENT_SECRET=

Google

1. Go to Google Cloud Console → Credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Configure the OAuth consent screen (External, app name, authorized domain)
4. Set Authorized JavaScript Origins to your frontend URL
5. Set Authorized Redirect URIs (see table below)
6. Copy Client ID and Client Secret to .env

Discord

1. Go to Discord Developer Portal → Applications
2. Create a new application
3. Navigate to OAuth2, copy Client ID and reset/copy Client Secret
4. Add Redirect URLs (see table below)
5. Copy values to .env

GitHub

1. Go to GitHub → Settings → Developer Settings → OAuth Apps
2. Create a New OAuth App
3. Set the homepage URL to your frontend URL
4. Set the Authorization callback URL (see table below)
5. Copy Client ID and generate/copy Client Secret to .env

Note: GitHub only allows one callback URL per OAuth app. You may need separate apps for development and production.

Redirect URIs

Each provider needs two callback URLs registered — one for login and one for account linking. The URLs are constructed from the API base URL defined in oauth-config.js.

Development (apiBase = http://localhost:4545):

• http://localhost:4545/auth/oauth/{provider}/callback
• http://localhost:4545/auth/oauth/link/{provider}/callback

Production (apiBase = https://api.manga-db.org):

• https://api.manga-db.org/auth/oauth/{provider}/callback
• https://api.manga-db.org/auth/oauth/link/{provider}/callback

Changing the Domain

If the API domain changes (e.g. moving from api.manga-db.org to a different domain):

1. Update backend-config.js port / domain as needed
2. The redirect URIs in oauth-config.js auto-derive from DB_ENV and the backend port — no manual URI changes needed
3. Update the redirect URIs in each provider’s developer console to match the new domain
4. Update CORS origins in server.js to include the new frontend domain

Login / Register Flow

GET /auth/oauth/:provider

Redirects the user to the provider’s consent screen to begin the OAuth flow.

No authentication required.

1. Generates a cryptographic state token (stored server-side, 10 min expiry)
2. Redirects to the provider’s authorization URL with the configured scopes
3. After consent, the provider redirects to the callback URL

GET /auth/oauth/:provider/callback

Handles the OAuth callback after the user authorizes with the provider.

No authentication required. The state parameter is validated against the server-side store.

1. Validates the state token
2. Exchanges the authorization code for an access token
3. Fetches the user’s profile from the provider
4. If the provider account is already linked to a user → logs that user in
5. If not → creates a new user account (auto-generates username from provider profile) and links the provider
6. Issues JWT tokens and sets the refreshToken cookie
7. Redirects to the frontend with ?oauth_success=1

On error, redirects to the frontend with ?oauth_error={reason} (e.g. access_denied, invalid_state, exchange_failed).

Account Linking

These endpoints allow authenticated users to connect or disconnect OAuth providers to their existing account.

GET /auth/oauth/link/:provider

Starts the account linking flow for an authenticated user.

Requires a valid refreshToken cookie.

1. Validates the refresh token
2. Generates a state token bound to the user
3. Redirects to the provider’s consent screen

GET /auth/oauth/link/:provider/callback

Handles the callback for account linking.

Requires a valid refreshToken cookie. The state parameter is validated.

1. Validates state and refresh token
2. Exchanges the code for an access token and fetches the provider profile
3. Checks that the provider account isn’t already linked to another user
4. Links the provider to the authenticated user’s account
5. Redirects to the frontend settings page

GET /auth/oauth/connections

Returns the list of OAuth providers linked to the authenticated user’s account.

Requires a valid refreshToken cookie.

[
    {
        "provider": "google",
        "provider_username": "John Doe",
        "provider_email": "john@gmail.com",
        "linked_at": "2026-01-15T10:30:00.000Z"
    },
    {
        "provider": "discord",
        "provider_username": "john#1234",
        "provider_email": "john@example.com",
        "linked_at": "2026-02-20T14:15:00.000Z"
    }
]

DELETE /auth/oauth/unlink/:provider

Unlinks an OAuth provider from the authenticated user’s account.

Requires a valid refreshToken cookie.

Validates that the user has an alternative login method before allowing the unlink:

• If the user has a password set → unlink is allowed
• If the user has no password and this is their only linked provider → unlink is rejected (would lock them out)

Configuration Reference

All OAuth settings live in src/config/oauth-config.js. The redirect URIs are auto-generated based on environment:

Provider Scopes

Database Table

OAuth connections are stored in the oauth_account table: