Integrations

Embed widget

Drop your Bynefit group into any website with one <script> tag. No iframes, no CSS conflicts — the widget renders in Shadow DOM so your site's styles stay put.

Quick start

Paste this anywhere on your page — usually right before </body>:

<script
  src="https://bynefit.com/widget.v2.js"
  data-key="bapi_tk_your_key_here"
  async></script>

The widget adds a small floating card in the corner of your site showing your group name, a live stat (members, campaign progress, next event), and a primary action button. Clicking it opens a contained side drawer (desktop) or bottom sheet (mobile) with everything else.

Get your key

1. Go to /dash/integrations/api-tokens.
2. Click Create a token.
3. Give it a label like "Website embed".
4. Check embed:widget in the scopes list. This is the only scope the widget needs.
5. Optionally list the domains allowed to use it (recommended — see below).
6. Click create. Copy the bapi_tk_… value immediately — it's shown once.

Or make a browser key

A browser key is made for a web page. It belongs to your Space, carries only the widget permission, and is refused on any website that is not listed under Embeds, so it is safe to show in your page source.

1. Go to /dash/integrations/api-tokens and choose Create key.
2. Choose Run in a visitor's browser and name the key.
3. Copy the bapi_pk_… value immediately. It is shown once.
4. Use it as data-key, and list your website under Embeds.

A browser key follows the allowed sites on your Embeds page, not a list of its own. A Space key with the widget permission keeps working exactly as before, including its own allowed-websites list.

Domain locking

If you listed allowed domains on the token, only those domains can load the widget; anything else is rejected with domain_mismatch, so a copy of your embed snippet on someone else's site won't work. To move embeds to a new domain, edit the token's allowed-domains list at /dash/integrations/api-tokens.

If the token has no list, the widget uses the allowed sites for your Space. Space admins add and remove sites themselves under Embeds in the dashboard, and every admin is emailed when the list changes. A site that is not on the list is rejected with domain_mismatch.

The Embeds hub

Space admins manage the snippet, the allowed websites and the widget's settings in one place: /dash/integrations/embeds. It also shows which websites tried to load your widget and were not on the list, with a one-click Allow. Every admin of the Space is emailed when a site is added or removed, the key is replaced, or the widget is switched off.

• An allowed site is an exact origin: scheme, host and port. https://example.com does not allow https://www.example.com or https://example.com:8443; add each one you use.
• Allowed sites are https, with no wildcards, paths, logins or IP addresses. You can allow up to 25. localhost is for non-production setups only.
• A key that has its own allowed-domains list uses that list instead of the Space's.
• During the move to enforcement, the hub shows the date after which sites not on the list stop loading, and lists the ones that would be blocked until then. Sites that were using the widget over plain http are allowed for a limited time and show as insecure: move them to https.

The key in the snippet. New snippets from the hub carry a browser key that starts with bapi_pk_. The hub shows the whole key once, when you press Generate a new snippet, and masks it afterwards; lost it? Generate a new one, and the old one stops working. A snippet that still carries a key starting with wk_ was switched off on 20 October 2026. Until then it keeps working, and the hub offers Copy the new snippet with a before and after. See Migrating from the legacy endpoint.

Customize

Pass options as extra data- attributes on the script tag:

Inline mode

Inline mode renders the widget directly into a section of your page — no floating trigger, no overlay. Often converts better when the widget is the page's main content (e.g. a donate landing page or a community sign-up section).

<div id="my-widget"></div>

<script
  src="https://bynefit.com/widget.v2.js"
  data-key="bapi_tk_your_key_here"
  data-mode="inline"
  data-target="my-widget"
  async></script>

Same hero card and section composition as the drawer — just rendered in document flow. The widget keeps its dark surface treatment; it doesn't inherit your host page's typography or colors.

Deep linking

Link directly to a part of the widget from anywhere on your page using URL hashes:

<a href="#bynli-donate">Support our work</a>

What's inside

The widget surfaces your team's identity (name, logo, accent color) and auto-picks a primary call-to-action based on what your team currently has live — donations, an active relief campaign, paid membership, or upcoming events.

The primary action is auto-picked based on your team's setup:

• Active relief campaign → Donate to the campaign
• Donations enabled → Donate
• Paid membership → Become a member
• Upcoming events → See events
• Otherwise → Visit page

Accessibility

• The drawer is a proper modal with keyboard focus management and Escape to close.
• The mobile sheet has the standard drag-handle and snap-to-dismiss.
• The trigger card respects prefers-reduced-motion — the rotating live state and entry animations are disabled for users who request it.
• All interactive elements have visible focus rings.

Troubleshooting

Widget doesn't appear at all

Open your browser's developer console (F12). Look for messages prefixed with [Bynefit] or [Bynefit v2].

• data-key is required — the attribute name is data-key, not data-bynli-key or anything else.
• config request failed: HTTP 403 — Token missing embed:widget scope — edit your token at /dash/integrations/api-tokens and check the embed:widget scope.
• config request failed: HTTP 403 — Invalid API token — the token doesn't exist or has been revoked. Create a new one.
• config request failed: HTTP 403 — Public-tier tokens cannot embed the widget — you used a developer key (bapi_pk_… from /dash/developers/keys) by mistake. The widget needs a Space key (bapi_tk_…) with the widget permission, or a browser key made on /dash/integrations/api-tokens.
• config request failed: HTTP 403 — domain_mismatch — the widget is loading from a domain that isn't registered for your token. Check your token's allowed-domains list.

Donate button leads to the wrong group

If a logged-in visitor clicks Donate and lands on their own group's checkout instead of yours, you're on an older version of the widget — update to widget.v2.js (or the latest widget.js).

Team logo broken / wrong URL

The widget always loads images from bynefit.com regardless of where it's embedded. If your logo shows a broken-image icon, the URL stored on your group page is probably wrong. Re-upload the logo from your group settings.

Open it programmatically

The deep-link hashes work programmatically too — just set location.hash:

document.getElementById('donate-btn')
    .addEventListener('click', () => {
        location.hash = 'bynli-donate';
    });