Hosted sites guide

What a site hosted by Bynefit can show, collect and read, how each piece signs in or does not need to, and what a site can never see. Written for the person building the site, and for the WordPress plugin.

To change a Bynefit-hosted site's files, from the file manager or with an AI agent, see Manage and edit a hosted site's files.

What a hosted site is

Kind	Where it lives	How Bynefit gets onto the page
Bynefit-hosted site	`your-site.site.bynefit.com`, or your own domain once it is verified	The Bynefit runtime script is added to every page automatically, just before `</body>`.
WordPress site with the Bynefit Connect plugin	Your own WordPress, managed by Bynefit or connected	The plugin reports to Bynefit with a signed key. Add the script tag below for the browser modules. See Site host API.
Any other website	Anywhere	Add one script tag with your site's slug in `data-team`. See below.

Which key do I use?

There is no single key for a hosted site. Each job has the credential that fits it.

Job	Credential	Runs where	Reference
Show events, resources and media; take a form; count a visit	None. The site's slug in the address identifies the site, and these endpoints return a live site's content or accept a submission. A site that is not live, or that does not exist, gets the same answer, so nothing reveals which sites exist.	The visitor's browser	Hosted sites API
Let a visitor sign in, then read their own engagements, documents and messages	The visitor's own access token from Sign in with Bynefit	The visitor's browser	Client portal API
Read your forms, form answers, events, payments and tasks	A Space API key (`bapi_tk_`)	Your server only	Authentication
Hear about a form submission as it happens	A webhook signing secret	Your server	Webhooks
Report a WordPress site's health and visit counts	A site key (`bynli_sh_`) and a signature	The WordPress server	Site host API
Use your own key for another service: payments, email, maps, AI	A site secret, saved under Settings, Keys & secrets	Bynefit's server, through a secure request or a form webhook	Keeping keys safe on a hosted site

Never put a Space API key, a site key, a webhook secret or any other service's secret key in a page. Hosted pages run JavaScript the site owner wrote, plus whatever else is on the page. Anything in a page can be read by every visitor. Save the key as a site secret instead. Every save is checked, and a page carrying one of your secrets is not published.

The runtime

On a Bynefit-hosted site the runtime loads itself. It checks whether the site is live, suspended or in maintenance, reads the site's config.json, loads the modules you ask for, records a page view and shows the Bynefit badge unless the site's plan removes it. A suspended site shows an unavailable page; a site in maintenance shows its maintenance message. Until a site is published, and while it is suspended, the public endpoints (events, forms, media, blocks) answer as if it did not exist, while the status check still reports it so this page can show. See which sites answer.

Use it on another website

HTMLyour site

<script src="https://bynefit.com/sites/bynli.js" data-team="your-site-slug" async></script>

data-team is your site's slug: 3 to 100 lowercase letters, numbers and hyphens.

Modules

Turn a module on with data-bynli="name" on an element, with data-bynli-ui="a,b" on html or body, or by listing names under ui.load in config.json.

Module	What it does	Talks to
`form`	Turns a form into a Bynefit form. Add `data-form-id="frm_..."` from the form builder. On an empty container element it also draws the form.	The form schema and submit endpoints
`events`	Lists upcoming or past events as cards, a list, or bare data. `data-limit`, `data-scope`, `data-style`.	The events endpoint
`widget`	Drops in a ready-made block: `data-widget-name="events"` or `"resources"`.	The widget endpoint
`donate`	A donate card or button with preset amounts. It sends the visitor to your Bynefit donation page.	Nothing. It builds a link.
`auth`	Sign in with Bynefit: buttons, a sign-in sheet, and attributes that show the signed-in person's name or picture.	The sign-in server. See OAuth 2.0 / OpenID Connect.
`chrome`	A header and footer from `config.json`. Mount points are `data-bynli-header` and `data-bynli-footer`.	Nothing
`modal`, `confirm`, `toast`, `lightbox`	Dialogs, confirmations, notices and image galleries.	Nothing

The site's config.json

A file at the root of the site, up to 32 KB. Only the keys below do anything.

config.jsonJSON

{
  "ui": { "load": ["form", "events", "auth"] },
  "chrome": {
    "header": { "brand": "Riverside Aid", "brandHref": "/", "links": [ { "label": "Get help", "href": "/help" } ] },
    "footer": { "legal": "Riverside Aid is a nonprofit." }
  },
  "auth": {
    "client_id": "site_0123456789abcdef01234567",
    "redirect_uri": "/auth/callback",
    "scopes": ["openid", "profile", "email"],
    "issuer": "default",
    "signup": true
  },
  "branding": { "show_powered_by": true }
}

auth.issuer of "default" means the Bynefit sign-in host. Anything else must be an https address.
auth.signup: false hides account creation.
branding.show_powered_by only matters on a plan that removes the badge: there the badge stays hidden unless this is true.
seo and analytics blocks are accepted, but the runtime does not read them.
public holds the site's public settings, written from Keys & secrets. The runtime does not read it; your own pages do. Never put a secret here. See Keeping keys safe on a hosted site.

What a hosted site can read and write

Data	Can a page read it?	How
Site status (live, suspended, maintenance)	Yes	Runtime status, no credential
Upcoming and past events, with sold counts and limits	Yes	Events endpoint or the `events` module, no credential. Only for a live site whose Space has turned on public events; cancelled and draft events are left out, and the window is two years either way.
Approved community resources	Yes	The `resources` widget, no credential
Media library	Yes	Media list, no credential
Form definitions	Yes	Form schema, no credential
Form submissions (what people typed)	No. A page can submit one, never read them.	Space owners read them in the dashboard. Your server can read them with a Space API key and the forms permission, or hear about each one by webhook.
Visitor analytics	No. A page can send a page view, never read the totals.	Dashboard
The signed-in person's own profile	Yes	Sign in, then the user-info endpoint. Only what they chose to share with this site.
The signed-in person's own engagements, documents, messages and bookings	Yes, theirs only	Client portal API
Other people's engagements, the member list, payments, donations, ticket buyers	No	Not exposed to a page by any endpoint
Site health, updates, content counts (WordPress)	No. The plugin sends them; the owner reads them in the Bynefit Sites app.	Site host API

Engagements

Engagements are the orders and requests a practice runs through Bynefit: a company formation, a service, a booking. A hosted practice site can build a client portal on them, and these are the only ways to reach engagement data:

A client signs in on the practice's site and the page reads that client's own engagements, documents and messages with the client's token.
The practice's own manager or admin signs in and the practice's admin surface reads the whole client list, with the same token flow. Do not put that surface on a public page.
An API key cannot read engagements. The Read API has no engagements endpoint, and there is not a webhook event for engagement changes.

The practice needs the engagements add-on switched on. Without it the portal answers 403 with addon_required.

Forms and webhooks

A form submitted from a hosted site fires the form.submitted webhook with source set to team_site and the site's slug and id. The submission's answers are never inside the webhook. The envelope carries the form's id and name, and the id of the submission, so your server can fetch the answers with a Space API key. Every non-registration form submission also opens a follow-up task for your Space's leaders, capped at 20 a hour per Space. If the person gave an email address, they get a confirmation email, or your own autoresponder if the form has one.

To send the answers themselves to a service you use, add a form webhook under Keys & secrets. It posts each answer to your address, with your own secret added on Bynefit's server. See form webhooks.

Shop and products

Planned There is no public API for a hosted site's shop, products or orders yet. The WordPress plugin has its own private checkout hand-off, which is not documented here.

Security notes

Tokens live in the browser. The sign-in module keeps tokens in localStorage, so any script injected into the page can read them. Set a Content Security Policy that allows only scripts you trust, and allow the sign-in host in frame-src and connect-src.
Everything typed for Bynefit stays out of your page. The sign-in sheet is a frame served by the sign-in host, which your page's script cannot read.
Form fields are not checked for type on the server. Only required fields are enforced, so validate on your side too.
Bots. The form module adds a hidden field that real people never fill in. A submission that fills it is dropped without a trace.
Sharing is the person's choice. What a site sees of an email, phone or business is decided per site by the person, and they can change it at any time at /dash/me/apps.