App Bridge

App Bridge is a JavaScript library that handles communication between your App Frontend and the Scompler platform. It manages session tokens and provides an authenticated fetch wrapper for making requests to your App Backend.

Installation

npm install @scompler/app-bridge

Quick start

Initialize App Bridge once at the root of your app. The host and language parameters are automatically read from the iframe URL query string.

import { createAppBridge } from '@scompler/app-bridge'

const app = createAppBridge({ appId: 'your-app-id' })

Making authenticated requests

app.authFetch(url, options?)

The recommended way to call your App Backend. Automatically attaches a session token to every request and retries once on 401.

const response = await app.authFetch('/api/data')
const data = await response.json()

Supports all standard fetch options:

const response = await app.authFetch('/api/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ item: 'foo' }),
})

app.getSessionToken()

Returns a valid session token (JWT). Use this when you need direct token access (for example, with a custom HTTP client).

const token = await app.getSessionToken()
myClient.setHeader('Authorization', `Bearer ${token}`)

For regular HTTP requests, prefer authFetch — it handles the full token lifecycle automatically.

Session tokens

Session tokens are short-lived JWTs issued by the platform at runtime. App Bridge fetches and caches them automatically.

Property	Value
Algorithm	HS256
Lifetime	60 seconds
Issued by	Scompler platform
Used for	App Frontend → App Backend

JWT payload:

{
  "iss": "pro.scompler.com",
  "account_id": 123,
  "sub": "456",
  "aud": "<app_id>",
  "iat": 1710000000,
  "exp": 1710000060
}

Claim	Description
iss	Issuer: the Scompler domain
account_id	The account the app is opened in
sub	User identifier
aud	Your app ID
iat	Issued at (Unix timestamp)
exp	Expires at (Unix timestamp)

Token expiry

Tokens expire after 60 seconds. authFetch handles this automatically — on a 401 response it fetches a fresh token and retries the request.

Verifying tokens on your backend

Your App Backend must verify the session token on every request.

import jwt from 'jsonwebtoken'

function verifySessionToken(token, appSecret, appId) {
  return jwt.verify(token, appSecret, {
    algorithms: ['HS256'],
    audience: appId,
  })
}

// Express.js middleware
function requireSession(req, res, next) {
  const authHeader = req.headers.authorization
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).send('Missing token')
  }
  try {
    const token = authHeader.slice(7)
    req.session = verifySessionToken(token, process.env.APP_SECRET, process.env.APP_ID)
    next()
  } catch {
    res.status(401).send('Invalid or expired token')
  }
}

API reference

createAppBridge(options)

Creates an App Bridge instance. Call once at the root of your app.

Option	Type	Required	Description
appId	string	yes	Your app identifier
host	string	no	Base64 URL-safe encoded account root URL. Falls back to host query param in the iframe URL
language	string	no	ISO 639-1 language code (e.g. "en", "de"). Falls back to language query param in the iframe URL

app.authFetch(url, options?)

Authenticated wrapper around the native fetch API.

Attaches a Bearer session token to every request. On 401, fetches a fresh token and retries once. Also sets Accept-Language based on the account's language.

app.getSessionToken()

Returns the cached session token if available, otherwise fetches a fresh one from the Scompler platform.

app.language

The resolved language string, or null if unavailable.