Skip to main content

Installation

The pre-authorization widget ships as a single-file loader hosted by Osigu. Include it once, then call OsiguPreAuth.mount(...) wherever you want the widget to render.

1. Include the loader​

Add this to your page's <head> (or wherever your bundler injects <script> tags):

<script src="https://widgets.osigu.com/v1/loader.js" async></script>

The loader is ~15 KB gzipped. It doesn't render anything on its own — it just exposes window.OsiguPreAuth when it finishes loading.

Version-pin recommended for production:

<script src="https://widgets.osigu.com/v1.2.0/loader.js" async></script>

The loader script is cache-immutable per version — long HTTP cache is safe.

2. Create a host element​

<div id="osigu-preauth" style="width: 720px; max-width: 100%;"></div>

The widget renders inside the host element. It takes 100 % of the host's width and expands vertically as steps are shown.

3. Mount the widget​

<script>
  document.addEventListener('DOMContentLoaded', async () => {
    await window.osiguReady;

    OsiguPreAuth.mount({
      container: '#osigu-preauth',

      // Auth token provider — the widget calls this whenever it needs a token.
      // MUST return a Promise<string> resolving to a valid access_token.
      getToken: async () => {
        const res = await fetch('/api/osigu/token', { credentials: 'include' });
        const { access_token } = await res.json();
        return access_token;
      },

      // Scope the widget to a specific sponsor (optional — omit for a picker).
      sponsorSlug: 'sponsor-sandbox',

      // Environment: 'sandbox' or 'production'
      environment: 'sandbox',

      // Locale
      locale: 'en',

      onComplete: (outcome) => {
        console.log('Authorization done:', outcome);
        // outcome.authorizations = [{ authorization_code, product_type, status, ... }]
      },
      onError: (err) => console.error(err),
      onClose: () => console.log('user closed the widget'),
    });
  });
</script>

window.osiguReady is a promise that resolves once the loader has attached window.OsiguPreAuth. Awaiting it means you don't have to worry about script-load ordering.

Framework wrappers​

React​

import { useEffect, useRef } from 'react';

export function PreAuthWidget({ getToken, sponsorSlug, onComplete }) {
  const ref = useRef(null);
  useEffect(() => {
    let handle;
    window.osiguReady.then(() => {
      handle = window.OsiguPreAuth.mount({
        container: ref.current,
        getToken,
        sponsorSlug,
        environment: 'sandbox',
        onComplete,
      });
    });
    return () => handle?.unmount();
  }, [getToken, sponsorSlug, onComplete]);
  return <div ref={ref} />;
}

Vue 3​

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
const host = ref(null);
let handle;
onMounted(async () => {
  await window.osiguReady;
  handle = window.OsiguPreAuth.mount({
    container: host.value,
    getToken: async () => (await fetch('/api/osigu/token')).json().then(j => j.access_token),
    sponsorSlug: 'sponsor-sandbox',
    environment: 'sandbox',
    onComplete: (out) => emit('complete', out),
  });
});
onBeforeUnmount(() => handle?.unmount());
</script>
<template><div ref="host" /></template>

The token proxy​

Never put the OAuth client_id / client_secret in the browser. The getToken callback should hit your backend, which exchanges credentials for a token, caches it, and returns the access_token to the browser. Concept: Obtaining tokens.

A minimal server-side proxy:

GET /api/osigu/token
  → server hits Osigu's /oauth/token (with cached client_id/secret)
  → server returns { access_token, expires_in } to the browser

Cache the token in the browser for its lifetime minus 60 seconds so the widget doesn't call getToken on every step.

Unmounting​

Call handle.unmount() (returned by mount) to tear the widget down. Safe to call multiple times.

Content Security Policy (CSP)​

If your app has a strict CSP, allow:

  • script-src https://widgets.osigu.com
  • connect-src https://widgets.osigu.com https://sandbox.osigu.com (or https://api.osigu.com in prod)
  • frame-src https://widgets.osigu.com (the OTP challenge renders inside an iframe)
  • img-src https://widgets.osigu.com data:

Next steps​

  • Configuration — the full option list.
  • Events — the callback shape for onComplete, onError, etc.