Authentication Flow

The desktop app never collects your Google or GitHub login inside its own window. Instead, it signs you in through your real system browser and receives your session back through a secure deep link. This keeps authentication in a trusted environment and keeps auth and the API on a single origin.

System-browser login

When you start sign-in in the app:

1. The app opens your default system browser to CodeSCE's auth site (the production auth origin), rather than loading the auth pages inside the app.
2. You authenticate there with Google or GitHub — in a normal, trusted browser where you can see the real URL and provider consent screen.
3. Because the OAuth start, callback, and desktop marker all happen on that one origin, the backend can complete sign-in and prepare a session for the app.

The app enforces this by intercepting attempts to navigate to auth pages and routing them to the external browser — so sign-in, sign-up, and onboarding always open outside the app window.

Why the system browser?

It means the app never handles your provider credentials directly, you're authenticating in a browser you already trust, and — because auth and the API end up on the same origin — you avoid the classic desktop pitfall where the app can't see the session the browser just created.

Deep-link return

Once you've authenticated, the backend hands your session back to the app through a custom-protocol deep link:

codesce://auth?token=<session-token>&redirect=<destination>

Here's what happens:

1. The app registers itself as the handler for the codesce:// protocol.
2. After sign-in, the browser opens the codesce://auth… link, which the OS routes to the app.
3. The app reads the token from the link and stores it as your session cookie (auth_token) in its own session — an httpOnly, lax cookie that persists for about 30 days.
4. The app then navigates to the redirect destination (your dashboard by default), now fully signed in.

Cross-platform handling

• Windows — a deep link arriving while the app is running (or at cold start) is delivered as a launch argument; the app's single-instance lock forwards it to the already-running window.
• macOS — the deep link is delivered through the system's open-url event.

Either way, the same handler sets your session and drops you into the app.

Signing out

Signing out clears the session cookie in the app and ends the session on the server, so any in-flight download links stop working immediately. You can sign back in the same way at any time.

Next step

With sign-in done, see how the app is used day to day in Local Workflow →.