@veryai/connect

Embed VeryAI palm sign-in as a QR code inside your own page. The user scans with the VeryAI app, and you get an OAuth authorization code — without ever navigating away.

npm install @veryai/connect

Or without a bundler:

<script src="https://unpkg.com/@veryai/connect@0/build/index.global.js"></script>

Usage

import { renderQR } from "@veryai/connect";

renderQR({
  container: "#very-login",
  clientId: "very_xxxxxxxxxxxx",
  redirectUri: "https://partner.example/oauth/callback",
  state: stateFromYourServer,
  onSuccess: ({ code, state }) => {
    // Single-use. Send it to your server and exchange it there.
    fetch("/api/very/callback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code, state }),
    });
  },
  onStatus: (status) => console.log(status), // waiting → scanned → verifying
  onError: (error) => console.error(error.code, error.message),
});

With the <script> build the same function is on window.VeryConnect.

The two rules that matter

1. redirectUri must be registered, and must be on this page's origin.

Register it in the Developer Portal first — Very matches it as an exact string and rejects anything else. Then note that in the default postmessage mode the authorization code is delivered with that URI's origin as the postMessage target. If your page is served from somewhere else, the browser silently drops the message and sign-in appears to do nothing. This SDK checks at startup and calls onError with origin_mismatch rather than letting you debug silence.

https://partner.example/oauth/callback works for a page on https://partner.example. https://api.partner.example/callback does not.

2. Exchange the code on your server. It buys tokens when combined with your client secret, which must never reach a browser. The code is single-use and expires in 10 minutes.

Options

| Option | Required | Description | | --- | --- | --- | | container | ✅ | Element or CSS selector to mount into | | clientId | ✅ | From the Developer Portal | | redirectUri | ✅ | Registered, and same-origin as this page — see above | | state | ✅ | Generate and verify server-side; returned untouched | | scope | | Defaults to openid | | nonce | | Compare against the nonce claim of the ID token | | codeChallenge / codeChallengeMethod | | PKCE. Keep the verifier on your server | | userId | | Re-verification: confirm it is the same person | | connectOrigin | | Defaults to https://connect.very.org | | selfRedirect | | postmessage (default), iframe, or top | | style | | light (default) or dark | | href | | https URL of a stylesheet applied inside the frame | | lang | | BCP-47 tag; defaults to the visitor's own preference | | onSuccess | | ({ code, state }) => void, fired once | | onStatus | | (status) => void | | onError | | ({ code, message }) => void |

renderQR returns a handle:

const login = renderQR({ ... });
login.reload();   // fresh session, e.g. after `expired`
login.destroy();  // unmount and stop listening

Delivery modes

postmessage is the default and the only one that keeps a single-page app on the same page.

iframe navigates the frame to your redirectUri — your callback page renders inside it. Useful if you would rather not run this SDK at all.

top navigates the whole tab. Browsers block top-level navigation from a cross-origin frame without user activation, and the gesture that completes this flow happens on the user's phone, so treat it as best-effort; it falls back to the iframe behaviour.

Statuses

| Status | Meaning | | --- | --- | | waiting | QR is on screen, not yet scanned | | scanned | App picked up the session; user is doing the palm scan | | verifying | Scan finished, exchanging for a code | | expired | Session timed out — the frame offers a refresh | | failed | Verification failed or was cancelled |

Errors

| Code | Meaning | | --- | --- | | origin_mismatch | redirectUri is not on this page's origin (see rule 1) | | invalid_request | Unknown clientId, or redirectUri is not registered for it | | session_expired | The 10-minute window elapsed | | verification_failed | The palm scan did not succeed | | undeliverable | Very holds a code but cannot determine where to send it |

On mobile

A QR is useless on the device that would scan it, so on phones the frame renders an "Open in VeryAI App" deep link instead and attempts to launch the app directly.

License

Apache-2.0