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 assertion is a server-to-server credential: it is created and spent entirely inside your backend, and never passes through the browser.

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 four values 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 each time the widget needs a token. It has a very short lifespan - 15 to 30 seconds is recommended, 120 seconds is the maximum - because it is a one-time proof of identity, not a session token. Fruga’s own reference implementation uses 16 seconds. Since the assertion is signed and spent within the same request on your server, it never needs to survive a round trip to the browser.

Required claims

Example payload

{
  "iss": "partner:1",
  "aud": "fruga:external_session",
  "iat": 1739819000,
  "exp": 1739819016,
  "jti": "0c3f5c3a-8d2e-4d4f-9e7a-62b2c0b7d8d1",
  "userRef": "user_123"
}

Fetching the audience

Rather than hardcoding aud, read it from the bootstrap endpoint using your Partner Key. This is the same configuration call the widget makes, and it is safe to call from your backend on every token request.

GET {FRUGA_API_URL}/widget/bootstrap?partnerKey=pk_dev_123

The response includes an auth object:

{
  "auth": {
    "mode": "external",
    "audience": "fruga:external_session",
    "issuer": "partner:1",
    "tokenTtlSeconds": 900
  }
}

Use auth.audience as the aud claim. The current sandbox value is fruga:external_session, but reading it from bootstrap means your integration keeps working if it changes.

JWT header

Set the algorithm to HS256 and include a kid header set to your PARTNER_KEY_ID. The kid is required - Fruga uses it to select which partner secret to verify the signature against.

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

Signing the assertion

Sign the JWT using HMAC-SHA256 with your PARTNER_SECRET. The secret is used as its raw UTF-8 bytes - do not base64-decode it first. The following examples show how to do this in common backend languages; both take the audience fetched from bootstrap.

Node.js

import * as jose from 'jose';

const generateAssertion = async (userRef, audience) => {
  const secret = new TextEncoder().encode(process.env.PARTNER_SECRET);

  return new jose.SignJWT({ userRef })
    .setProtectedHeader({
      alg: 'HS256',
      typ: 'JWT',
      kid: process.env.PARTNER_KEY_ID,
    })
    .setIssuedAt()
    .setIssuer(process.env.ISSUER)
    .setAudience(audience)
    .setExpirationTime('16s')
    .setJti(crypto.randomUUID())
    .sign(secret);
};

Python

import jwt
import uuid
import time
import os

def generate_assertion(user_ref, audience):
    now = int(time.time())
    payload = {
        "iss": os.environ["ISSUER"],
        "aud": audience,
        "iat": now,
        "exp": now + 16,
        "jti": str(uuid.uuid4()),
        "userRef": user_ref,
    }
    return jwt.encode(
        payload,
        os.environ["PARTNER_SECRET"],
        algorithm="HS256",
        headers={"kid": os.environ["PARTNER_KEY_ID"]},
    )

Exchanging the assertion

Your backend posts the assertion to the token exchange endpoint and returns the result to the browser. The response contains the accessToken your onTokenRequired callback should return.

POST {FRUGA_API_URL}/auth/external/token
Content-Type: application/json

{ "assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleV8xIn0..." }

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. Your endpoint passes it back to the browser, and the widget uses it for all subsequent requests. This is separate from your assertion - it is Fruga’s session token, and beyond returning it from onTokenRequired you do not need to store, refresh, or interact with it directly.

The access token has a 15-minute lifetime (also advertised as auth.tokenTtlSeconds on bootstrap). The widget manages its own refresh cycle - if a user’s session extends beyond that, the widget calls onTokenRequired again, your backend signs and exchanges a fresh assertion, and the widget continues uninterrupted. Make sure your token 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:

Two things follow from this design. Your PARTNER_SECRET is only ever used inside one server function, so the surface area for a leak is a single file. And because your endpoint decides which userRef to sign for, the browser can never request a token for a user other than the one it is authenticated as - provided you check the session server-side before signing.