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 Creator Membership plan that currently includes Desktop App Login.
• An approved, non-archived 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.

Register your app

1. Open Modder Dashboard → Mods.
2. Open the action menu for an approved, non-archived mod.
3. Select Desktop App Login.
4. Enter a globally unique app ID using lowercase letters, numbers, and hyphens. A useful pattern is your-mod-slug-installer.
5. Select Submit for review.
6. Wait for Modsy's administrator review before enabling login in a public release.

Registration status

• Pending: the request is waiting for review and cannot start login sessions.
• Approved and active: the app may use the desktop authentication endpoints.
• Approved but disabled: the creator disabled the integration; existing sessions are revoked.
• Changes requested: review the administrator's note, correct the request, and resubmit.
• Revoked: an administrator stopped the registration. Contact Modsy support before shipping another client.
• Paused — paid plan required: the registration remains recorded, but runtime access is unavailable until an eligible paid Creator 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 creator 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 Login dialog. This stops new login sessions and revokes existing sessions for that app. Re-enabling requires an eligible paid Creator Membership.

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.