Login widget

Add Sign in with Insy to any page with a single script tag — a public OAuth client that runs PKCE in the browser and returns tokens to your code.

The login widget is a drop-in script tag that renders a Sign in with Insy button and completes the whole OAuth flow in the browser. It is a public client and uses PKCE, so it needs no client secret and no backend on your side.

Button builder

Pick a look and copy the tag. The preview uses the widget’s real styles; it does not sign anyone in.

<script async src="https://insy.io/oauth/widget.js"
        data-client-id="oac_your_client_id"
        data-scope="memberships.read"
        data-on-auth="onInsyAuth"></script>

Copy and paste

The button renders inline where the script tag sits — place the tag where you want it.

<script
  async
  src="https://insy.io/oauth/widget.js"
  data-client-id="oac_9f2c41e7a83b06d5c4e19f27"
  data-scope="memberships.read"
  data-lang="en"
  data-size="md"
  data-on-auth="handleInsyAuth"
></script>

<script>
  function handleInsyAuth(result) {
    if (!result.ok) {
      console.warn("Insy sign-in failed:", result.error, result.errorDescription);
      return;
    }
    // Send the token to your own backend. Do not trust the browser with privileged work.
    fetch("/api/insy/session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ accessToken: result.accessToken }),
    });
  }
</script>

Attributes

data-on-auth is a name, not an expression

The value is resolved as a dotted path against window, so data-on-auth="myApp.onInsyAuth" finds window.myApp.onInsyAuth. It is never evaluated as JavaScript, which is what lets the widget run under a strict Content Security Policy. Anything that is not a plain dotted path — a call, an arrow function, an inline statement — will not resolve.

<script src="https://insy.io/oauth/widget.js" data-on-auth="myApp.onInsyAuth" ...></script>

<script src="https://insy.io/oauth/widget.js" data-on-auth="onInsyAuth(event)" ...></script>

Receiving the result

There are two ways to get the result, and both fire for every attempt. Pick whichever fits your codebase — you do not need both.

<script>
  window.handleInsyAuth = function (result) {
    if (result.ok) {
      console.log("scope granted:", result.scope);
      console.log("expires in:", result.expiresIn, "seconds");
    } else {
      console.warn(result.error, result.errorDescription);
    }
  };
</script>

<script
  async
  src="https://insy.io/oauth/widget.js"
  data-client-id="oac_9f2c41e7a83b06d5c4e19f27"
  data-scope="memberships.read products.read"
  data-on-auth="handleInsyAuth"
></script>

document.addEventListener("insy-auth", async (event) => {
  const result = event.detail;

  if (!result.ok) {
    showError(result.error);
    return;
  }

  await fetch("/api/insy/session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ accessToken: result.accessToken }),
  });
});

The success object

{
  ok: true,
  state: "…",           // the state value tied to this attempt
  accessToken: "…",     // opaque; send it as Authorization: Bearer <token>
  refreshToken: "…",    // opaque; 30 days, sliding
  expiresIn: 3600,      // seconds until the access token expires
  scope: "memberships.read",
  tokenType: "Bearer"
}

Both tokens are opaque random strings. Do not try to decode or parse them — they carry no claims. scope reflects what was actually granted, which is what you should branch on, not what you asked for.

The failure object

{
  ok: false,
  error: "popup_blocked",
  errorDescription: "…"
}

error may also carry any other OAuth error returned by the authorize endpoint, such as invalid_scope for a scope your client is not registered for. Handle unknown values with a generic failure path rather than assuming the list above is exhaustive at runtime.

How the popup flow works

This split is what makes a browser-only client safe: the authorization code is useless without the matching code_verifier, which never leaves your page, so an attacker who intercepts it — from a log, a referrer header, or a malicious extension reading the popup URL — cannot redeem it. The code is also single-use and expires after 60 seconds.

Registering web origins

The widget only runs on origins registered on the client at Account → Developer → OAuth clients. An origin is the scheme, host and port together.

Each entry is either an exact origin or a host with one leading *. label, which covers every subdomain beneath it at any depth — the latter exists for per-branch preview deploys. The scheme and the port are never wildcarded.

You do not register a redirect URI for the widget. The flow always returns to the callback page Insy hosts at https://insy.io/oauth/widget-callback, accepted for any client with at least one web origin registered — your web origins are what gate where the widget runs.

Exact origins

https://shop.example
https://app.shop.example
http://localhost:5173

https://shop.example matches only https://shop.example. It does not cover https://www.shop.example, http://shop.example or https://shop.example:8443 — register each one you actually use.

Wildcard subdomains

https://*.vercel.app

If you need the apex as well as the previews, register both https://vercel.app and https://*.vercel.app.

Every host under the suffix is authorised, at every depth, to run the widget and to call the token endpoint cross-origin. Register the narrowest suffix you control — on a shared preview domain that means asking for exact origins instead.

Security

If your application has a backend that can hold a secret, the server-side flow with a confidential client keeps tokens out of the browser entirely and is the stronger option.