Add Modsy login to your desktop app

How it works

1. Your desktop app asks Modsy to start a short-lived login session.
2. It opens a Modsy URL in the user's normal browser.
3. The user signs in, compares the displayed code, and approves or denies the request.
4. Your app polls Modsy with its per-login proof verifier.
5. Modsy returns authentication tokens and the current entitlement for the linked mod.
6. Your app unlocks only when the entitlement permits access and checks it again over time.

The desktop app never talks directly to Patreon or Lemon Squeezy. It does not need provider campaign IDs, product IDs, credentials, or business rules.

Before you start

You need:

• A paid Modder Membership plan or active paid-plan trial that currently includes Desktop App Auth API.
• An approved, published Modsy mod that you own.
• A desktop application able to open the system browser and make HTTPS requests.
• A secure operating-system credential store for refresh tokens.
• A stable random installation identifier that contains no personal information.

The linked mod may be public, Patreon-protected, Lemon Squeezy-protected, or allow either provider. Desktop entitlement automatically follows the mod's current access configuration.

Mod Leak Tracing helps modders trace shared mod files back to the account that received the installed copy. It requires integration with your own installer. Logged-in modders whose Modder Membership plan includes Desktop App Auth API can access the feature and its private documentation from their Modder Dashboard.

Generate your app ID

1. Open Modder Dashboard → Mods.
2. Open the action menu for an approved, published mod.
3. Select Desktop App Auth API.
4. Select Generate app ID. Modsy generates a random, unique ID and activates the integration immediately; no administrator review is required.
5. Use the copy button beside the ID and configure it in your installer. The dialog stays open so you can copy it immediately.

An existing app ID stays unchanged. If you have an older pending or rejected registration, select Activate existing app ID to activate it without another review. Revoked registrations require Modsy support and cannot be replaced through this button.

Registration status

• Active: the app may use the desktop authentication endpoints.
• Disabled: the modder disabled the integration; existing sessions are revoked.
• Ready to activate: an older pending or rejected registration can be activated with its existing ID, without admin review.
• Revoked: an administrator stopped the registration. Contact Modsy support before shipping another client.
• Paused — eligible membership required: the registration remains recorded, but runtime access is unavailable until an eligible paid Modder Membership is active again.

Build the login flow

Every new integration must use a fresh S256 proof key for every login attempt:

1. Generate a cryptographically random code_verifier containing 43–128 valid characters.
2. Hash it with SHA-256 and Base64URL-encode the result without padding to create code_challenge.
3. Send the challenge when starting login.
4. Keep the verifier in memory until polling finishes. Do not log it or treat it as a reusable account credential.
5. Poll no faster than the interval returned by Modsy.
6. Stop on approval, denial, expiry, or when the session lifetime ends.

Open the complete Desktop Auth API reference for endpoint payloads, response examples, entitlement values, and error handling.

Handle authentication and entitlement separately

An approved login proves that the user authenticated their Modsy account. It does not prove that the user can access the linked product.

Unlock protected functionality only when entitlement.access is:

• active
• grace

Keep the product locked for no_access, expired, revoked, or banned. Re-check entitlement when the app starts, before protected actions, after refreshing a token, and periodically while the app is running.

For public mods, the entitlement is active while the linked mod and app registration remain available. For protected mods, Modsy resolves the current Patreon, Lemon Squeezy, or manual entitlement server-side.

Release the installer safely

• Publish the official installer through the linked Modsy mod page.
• Sign executable releases with the operating system's code-signing mechanism.
• Show the Modsy user code in your app so the user can compare it with the browser page.
• Never embed a reusable client secret in the executable; it can be extracted.
• Never store or request Patreon or Lemon Squeezy credentials.
• Store Modsy refresh tokens in the OS credential store and never include them in logs or crash reports.
• Use a random stable installation ID, not an email address, username, or machine name.

The exact-code confirmation and linked publisher/mod details help users notice an impersonating client. The S256 proof key prevents another process from redeeming a login session without the matching verifier.

Test the integration

Before release, verify all of these cases:

1. The browser opens the complete verification URL and displays the same user code as the app.
2. Denial and expiry stop polling without unlocking the product.
3. An authenticated user without entitlement receives approved with no_access and remains locked.
4. An entitled user receives active or grace and is unlocked.
5. Refresh rotates both tokens and the previous refresh token no longer works.
6. Logout clears local tokens and revokes the session.
7. Revoking the session from Profile Settings → Security stops refresh and entitlement checks.
8. Disabling the modder integration stops pending and active sessions.
9. Archiving or unpublishing the linked mod prevents continued product access.

Disable or revoke access

An owner can select Disable and revoke sessions in the Desktop App Auth API dialog. This stops new login sessions and revokes existing sessions for that app. Re-enabling requires an eligible paid Modder Membership or active paid-plan trial.

Users can revoke their own desktop sessions from Profile Settings → Security. Your client must handle TOKEN_REVOKED by clearing local tokens and returning to a signed-out state.