Install and embed - MyGigsters Docs

Once you have your credentials and package tag, setup takes less than 30 minutes. See Get access.

How authentication works

The components use a short-lived JWT for every API call. Your backend exchanges its Basic Auth credentials for a 10-minute JWT, then passes it to the component when it mounts. Basic Auth credentials are never sent to the browser.

Install the package

npm install github:mygigsters/super-annuation#v2.1.0

Always pin to a specific version tag. A QA tag, for example v2.1.0-qa, is available for testing against staging.

Store your Basic Auth credential securely

Keep the credential in a server-side store, such as AWS Secrets Manager, HashiCorp Vault, KMS, or a backend environment variable. It must never appear in front-end code or in any variable that ships to the browser.

# Example — backend environment variable (or use your preferred secret store)
SUPER_BASIC_AUTH=your-base64-encoded-credential

Create a backend token endpoint

Your backend calls POST /widget/session to exchange Basic Auth for a 10-minute JWT.

POST https://qa-super.mygigsters.com.au/widget/session
Authorization: Basic <base64(apiUsername:apiPassword)>

→ { "token": "eyJhbGci...", "tokenType": "Bearer", "expiresIn": 600 }

Expose the token to your front end through an internal endpoint:

GET /api/super-token
→ { "accessToken": "eyJhbGci..." }

Never call /widget/session from the browser. It only accepts Basic Auth. Passing a Bearer token returns 401.

Import the stylesheet

Add this once at your app entry point:

import 'super-annuation/style.css'

Mount a component

Choose the component that fits. See Choose a component.

Mount SuperManagementEmbed

No routing is needed. Fetch the token from your backend at session start, pass it in config.accessToken, and provide onTokenExpired so the token renews automatically.

SuperPage.jsx

import { useState, useEffect } from 'react'
import { SuperManagementEmbed } from 'super-annuation'
import 'super-annuation/style.css'

export default function SuperPage() {
  const [accessToken, setAccessToken] = useState(null)

  useEffect(() => {
    fetch('/api/super-token')
      .then(r => r.json())
      .then(({ accessToken }) => setAccessToken(accessToken))
  }, [])

  if (!accessToken) return null  // or a loading state

  return (
    <YourSidebarLayout>
      <SuperManagementEmbed
        config={{
          accessToken,
          frontendBaseUrl: `${window.location.origin}/super`,
        }}
        onTokenExpired={async () => {
          const { accessToken } = await fetch('/api/super-token').then(r => r.json())
          return accessToken
        }}
      />
    </YourSidebarLayout>
  )
}

Mount SuperApp

SuperApp requires React Router v6 or later. First, add a catch-all route:

import { Routes, Route } from 'react-router-dom'
import SuperRouteWrapper from './SuperRouteWrapper'

<Routes>
  <Route path="/super/*" element={<SuperRouteWrapper />} />
</Routes>

Then create the wrapper:

SuperRouteWrapper.jsx

// SuperRouteWrapper.jsx
import { useState, useEffect } from 'react'
import { SuperApp } from 'super-annuation'
import 'super-annuation/style.css'

const SUPER_PATH = '/super'

export default function SuperRouteWrapper() {
  const [accessToken, setAccessToken] = useState(null)

  useEffect(() => {
    fetch('/api/super-token')
      .then(r => r.json())
      .then(({ accessToken }) => setAccessToken(accessToken))
  }, [])

  if (!accessToken) return null  // or a loading state

  return (
    <YourSidebarLayout>
      <SuperApp
        embedded
        basename={SUPER_PATH}
        config={{
          accessToken,
          frontendBaseUrl: `${window.location.origin}${SUPER_PATH}`,
        }}
        onTokenExpired={async () => {
          const { accessToken } = await fetch('/api/super-token').then(r => r.json())
          return accessToken
        }}
      />
    </YourSidebarLayout>
  )
}

Token expiry

The component manages the token lifecycle for you. It calls onTokenExpired 60 seconds before the token expires, so normal sessions never see a 401. onTokenExpired must return the new token string. If it returns nothing or throws, the component shows a session-expired error. If several requests expire at once, your token endpoint is still only called once.

Add an error boundary

Wrap a super component in an error boundary so an unexpected error doesn’t affect the rest of your application:

import { Component } from 'react'
import { SuperManagementEmbed } from 'super-annuation'

class SuperErrorBoundary extends Component {
  state = { hasError: false }
  static getDerivedStateFromError() { return { hasError: true } }
  render() {
    if (this.state.hasError) return <p>Something went wrong. Please refresh.</p>
    return this.props.children
  }
}

export default function SuperPage() {
  return (
    <SuperErrorBoundary>
      <SuperManagementEmbed config={config} />
    </SuperErrorBoundary>
  )
}

​How authentication works

​Mount SuperManagementEmbed

​Mount SuperApp

​Token expiry

​Add an error boundary

How authentication works

Mount SuperManagementEmbed

Mount SuperApp

Token expiry

Add an error boundary