Authentication

How the model works

When a user opens your platform and the Relay widget loads, three things happen in sequence — two of which are invisible to the user entirely.

The key insight is that Fruga never manages a login flow for your users. You remain the authority on who is authenticated in your platform. Fruga simply trusts your signed assertion and acts on it.

Your credentials

Fruga provides two credentials for each environment (sandbox and production). You will receive these from the Fruga integrations team before you begin your integration.

The assertion JWT

An assertion is a standard JWT that your backend generates fresh for each widget session. It has a very short lifespan — 60 seconds is recommended, 120 seconds is the maximum — because it is a one-time proof of identity, not a session token. Once exchanged for a Fruga access token, the assertion cannot be reused.

Required claims

Example payload

{
  "iss": "partner:p_123",
  "aud": "fruga:external_token_exchange",
  "iat": 1739819000,
  "exp": 1739819060,        // 60 seconds after iat
  "jti": "0c3f5c3a-8d2e-4d4f-9e7a-62b2c0b7d8d1",
  "userRef": "user_123"
}

JWT header

Set the algorithm to HS256. No other fields are required in the header for V1.

{
  "alg": "HS256",
  "typ": "JWT"
}

Signing the assertion

Sign the JWT using HMAC-SHA256 with your Signing Secret. The following examples show how to do this in common backend languages.

Node.js

import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';

const generateAssertion = (userId) => {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      iss: 'partner:p_123',
      aud: 'fruga:external_token_exchange',
      iat: now,
      exp: now + 60,
      jti: uuidv4(),
      userRef: userId,
    },
    process.env.FRUGA_SIGNING_SECRET,
    { algorithm: 'HS256' }
  );
};

Python

import jwt
import uuid
import time
import os

def generate_assertion(user_id):
    now = int(time.time())
    payload = {
        "iss": "partner:p_123",
        "aud": "fruga:external_token_exchange",
        "iat": now,
        "exp": now + 60,
        "jti": str(uuid.uuid4()),
        "userRef": user_id,
    }
    return jwt.encode(
        payload,
        os.environ["FRUGA_SIGNING_SECRET"],
        algorithm="HS256"
    )

What Fruga checks when it receives your assertion

Understanding the server-side verification steps helps you debug failures quickly. When your assertion reaches Fruga’s POST /auth/external/token endpoint, the following checks run in order:

All checks must pass. If any fail, the exchange returns an error and no access token is issued.

The Fruga access token

On a successful exchange, Fruga issues its own short-lived access token to the widget. This is separate from your assertion — it is Fruga’s internal session token and is handled entirely by the widget SDK. You do not need to store, refresh, or interact with it directly.

The access token has a 15-minute lifetime. The widget manages its own refresh cycle — if a user’s session extends beyond 15 minutes, the widget will silently request a new assertion from your backend and exchange it for a fresh access token. Make sure your assertion endpoint remains available for the duration of a user’s session.

Troubleshooting

The following table covers the most common authentication failures and their causes.

Security considerations

The assertion pattern is designed so that sensitive credentials never touch the browser. Here is a summary of what is safe where:

The widget runs inside an iframe, which means your host page is isolated from the Fruga access token by browser same-origin policy. Even if a user inspects your page, they cannot extract the Fruga session.