DEV Community

Химяк Павел
Химяк Павел

Posted on Originally published at partna.dev

Your frontend should not talk to your partner API

An affiliate integration usually starts the same way. The partner API needs a tenant key, the site
needs to call the API, and the quickest path is to put the key in the frontend and call it from
there. It works. It also ships three problems that show up months later, in production, at the worst
possible moment.

I built a small service to avoid all three and released it as MIT: partna-bridge. But the
interesting part is not the code — it is why the naive integration breaks.

Failure one: the key is in the browser

Open the network tab on almost any small affiliate programme and you will find an API key, a project
token or a signed URL in the JavaScript bundle. Anyone can copy it, then call your partner API and
award themselves a commission.

The fix is not "hide the key a bit better". A key that reaches the browser is public, full stop. The
only real option is a server-side proxy that holds the key in an environment variable and never
returns it in a response.

Failure two: attribution lives in a tab

The second failure is quieter. Most implementations store the referral code in sessionStorage or in
a JavaScript variable. That survives navigation, not a closed tab. A visitor clicks a partner link,
looks around, closes the page, comes back a week later and buys. The partner gets nothing, and the
partner is right to be annoyed.

What you want is a cookie on the customer's own domain: HttpOnly, SameSite=Lax, with Secure set
when the public URL is https, and a lifetime measured in weeks rather than minutes. The code then
travels with the browser, not with one page view.

Failure three: webhooks everywhere

The engine needs to tell the site that a payment or a refund happened. If every service in the
project accepts that webhook, signature verification gets implemented three times, in three styles,
and one of them inevitably skips the check.

One public endpoint that verifies the signature over the raw body, deduplicates by event id and
answers 202 is easier to reason about than three handlers that disagree.

What the bridge does

partna-bridge runs on the customer's server, in front of the engine:

visitor  --/r/CODE-->  bridge  --Set-Cookie-->  visitor
frontend --config, claim-->  bridge
backend  --order, refund, partner-link-->  bridge  --X-API-Key-->  engine
engine   --webhook, signed-->  bridge
Enter fullscreen mode Exit fullscreen mode

Money never passes through it. It is a proxy with a cookie, a queue and a signature check:

  • GET /health — alive, and whether the tenant key is configured;
  • GET /v1/config — brand, currency, destination URL for the frontend;
  • GET /r/<code> — sets the binding cookie and redirects back with ?ref=<code>;
  • POST /v1/claim — binds a client to a code, from the body or from the cookie;
  • POST /v1/order, POST /v1/refund — server-only, behind a bearer token;
  • POST /webhooks/engine — engine events with X-Partner-Signature.

The frontend must never be able to call order. Otherwise you have rebuilt failure one with extra
steps.

Running it

git clone https://github.com/partna-dev/partna-bridge
cd partna-bridge
./scripts/install.sh
Enter fullscreen mode Exit fullscreen mode

The script generates secrets, builds the container, waits for /health and prints what is left to
connect. Configuration is a handful of variables:

BRIDGE_ENGINE_URL=https://networks.partna.dev
BRIDGE_ENGINE_API_KEY=...        # server-side only
BRIDGE_PUBLIC_URL=https://app.example.com
BRIDGE_DESTINATION_URL=https://app.example.com
BRIDGE_BRIDGE_TOKEN=...          # bearer token for order/refund
BRIDGE_WEBHOOK_SECRET=...        # webhook signature
Enter fullscreen mode Exit fullscreen mode

Until a key is set, /health returns key_configured: false and protected endpoints answer 503.
That is deliberate: a half-configured bridge should look broken, not behave unpredictably.

What is actually tested

Twelve tests, and they cover the things that break in production rather than the happy path:

  • the tenant key never appears in a response;
  • the binding cookie is set, is HttpOnly, and survives;
  • an order without the bearer token is rejected;
  • a webhook with a wrong signature is dropped;
  • a repeated event id is marked as a duplicate.

The outbox deserves a note: BRIDGE_OUTBOX_MODE=queue writes orders and refunds to SQLite and answers
202, then retries with backoff. inline sends immediately and fails loudly. For a partner engine on
the other side of the internet, the queue is the sane default — a customer's checkout should not fail
because someone else's API hiccuped.

Honest limitations

  • The processed event list lives in memory, so after a restart a repeated event passes again. The host should still deduplicate.
  • claim is rate-limited per address; a public site behind a proxy needs its own protection.
  • It is not a billing system, not an analytics platform, and it will not design your commission plan.

Links

Top comments (1)

Collapse
 
vidakhoshpey22 profile image
Vida Khoshpey •

lol what an interesting title I followed your github and star it was nice 😍