# Partner integration guide

From first conversation to a working integration: get set up, get your keys, send events, receive webhooks, sign people in with Bynefit and put Bynefit on your own pages. Each step says who does it, and what is not built yet.

> **What a partner is.** An organization that runs part of its business on Bynefit: its websites, its event data, sign-in, embeds and more, managed from one partner console. It is not the same as a Space that only wants an API key: anyone can make a [developer key](https://bynefit.com/docs/getting-started) or a Space key. Partners are enrolled with Bynefit, and after that set up what they need themselves.

## The path at a glance

| Step | Who does it | Where | State |
| --- | --- | --- | --- |
| 1. Get enrolled | You ask, Bynefit sets it up | [Support](https://bynefit.com/support?category=technical) | (By approval) |
| 2. Find your keys | You | [/dash/partner/keys](https://bynefit.com/dash/partner/keys) | (Available) |
| 3. Add your websites and events | A manager of your Space | Partner console, *Keys* and *Events* | (Available) |
| 4. Send events | Your code | [Partner events](https://bynefit.com/docs/partner-events) | (By approval) |
| 5. Receive webhooks | A Space admin, then your code | [/dash/integrations/webhooks](https://bynefit.com/dash/integrations/webhooks) | (Available) |
| 6. Sign people in | A Space manager, then your code | [/dash/partner/sign-in](https://bynefit.com/dash/partner/sign-in) | (Available) |
| 7. Embed Bynefit on your pages | A Space admin | [/dash/integrations/embeds](https://bynefit.com/dash/integrations/embeds) | (Available) |
| 8. Ask for what is missing | You | Partner console, *Requests* | (Available) |

## 1. Get enrolled

Tell [support](https://bynefit.com/support?category=technical) you want to be a partner and which Space is yours. Bynefit records your agreement and links your partner record to your Space. That part is ours to do, because it is a signed agreement and it decides which people see your data. Admins and managers of your Space then open the console at [/dash/partner](https://bynefit.com/dash/partner) and set up the rest themselves: websites, events and the details each event carries. A partner goes live once these are in place:

- the Partner Agreement is recorded, with your contracting entity;
- a decision on the credit rate is recorded (zero is a decision);
- your Space is linked;
- at least one website and at least one event are registered, which you can do from the console.

Until then the program is in `draft`: test events work, and nothing live is counted. The console has Home, Catalog (what exists, with its state), Requests, Keys, Events, Brand kit, Credits and the sign-in recipe. Bynefit sees every change you make there and can step in if something looks wrong, but nothing waits for us.

## 2. Find your keys

The Keys page shows your partner key and tells you what is ready. There are two different kinds of secret to keep apart.

| Key | Starts with | Secret? | Used for |
| --- | --- | --- | --- |
| Partner key | `pbk_` | No. It only says who you are. | Sending events from a web page or with a signature. |
| Signing secret | a long random string | Yes. Servers only. | Signing event requests. Shown once when it is issued. |
| Space API key | `bapi_tk_` | Yes. Servers only. | The [Read API](https://bynefit.com/docs/authentication), the token way of sending events, and the embed widget. |

Lost the signing secret? A manager of your Space makes a new one on the Keys page and sees it once. Making a new one stops the old one working at once.

## 3. Add your websites and events

To send events from a browser, the address your pages are served from has to be on your list, written as `https://example.com` (no path). Add it under *Your websites* on the Keys page and it works straight away, up to 20. Plain `http` is only accepted for `localhost`. Sending from your own servers needs no website.

Under Manage events you add an event, switch one off, and choose the details each event carries: a name and whether it is text, a number or yes/no, up to 10 per event. A new detail is accepted from the next event you send. Removing one stops it being accepted; events you already sent keep it. Details that would hold personal data, like a name, email, phone number, address, location, ID number or IP address, are refused.

## 4. Send events

Pick the browser way for pages and the signed way for servers and app backends. The full request, the worked signature example, errors and limits are on [Partner events](https://bynefit.com/docs/partner-events). A first check that costs nothing:

**cURL**

```bash
URL="https://bynefit.com/dash/api/v1/beacons/collect"
KEY="pbk_YOUR_PARTNER_KEY"
SECRET="YOUR_SIGNING_SECRET"

TS=$(date +%s)
AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
BODY="{\"test\":true,\"events\":[{\"id\":\"test-$TS\",\"name\":\"listing_viewed\",\"at\":\"$AT\"}]}"
SIGNATURE=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -i -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: $KEY" \
  -H "X-Beacon-Timestamp: $TS" \
  -H "X-Beacon-Signature: $SIGNATURE" \
  -d "$BODY"
```

You should see `202` and `"test": true`. Take `"test": true` out when you are ready to count real events.

## 5. Receive webhooks

A webhook tells your server when something happens in your Space: a form is submitted, a person joins, a donation arrives. A Space admin adds your address at [/dash/integrations/webhooks](https://bynefit.com/dash/integrations/webhooks) and copies the signing secret once. Your server checks the signature on every delivery and answers `2xx`. The envelope, headers, events, retries and ready-to-run verification code are on [Webhooks](https://bynefit.com/docs/webhooks).

Webhooks are about your own Space. They do not carry your partner events, and there is not a webhook for engagement or Business Setup changes.

## 6. Sign people in with Bynefit

People can sign in to your site or app with their Bynefit account. A manager of your Space opens [/dash/partner/sign-in](https://bynefit.com/dash/partner/sign-in), names the client, and lists your return addresses: web pages, and for a native app an `https` link on your own domain. You get a `client_id`; there is no client secret, so the flow uses PKCE. The recipe shows your live endpoints. The protocol, with code, is on [OAuth 2.0 / OpenID Connect](https://bynefit.com/docs/oauth).

- Name, picture and email are available straight away.
- Creator status and earnings are available  (By approval) Bynefit approves each use first.
- A sign-in sheet that opens on your own page, without leaving it, works for the websites you list as in-page sign-in sites in the recipe.
- Return to a native app through its own link scheme, your domain written backwards (`vip.example.app://callback`)  (By approval) Bynefit approves each scheme for you first. A verified `https` link on your domain needs no approval.

## 7. Put Bynefit on your pages

A Space admin copies the widget snippet from [Embeds](https://bynefit.com/dash/integrations/embeds) in the dashboard and lists the websites that may load it. See [Embed widget](https://bynefit.com/docs/widget). If your own website is a Bynefit-hosted site, the [hosted sites guide](https://bynefit.com/docs/hosted-sites) covers forms, events, resources and sign-in on it.

## 8. Ask for what is missing

The Catalog lists what exists today and what does not. Most of it you switch on yourself. Use *Requests* to ask for something that is not built, or for the few things Bynefit reviews first: member emails, managing the shared directory, creator status and earnings at sign-in, and anything about your credit terms. A request gets a reply on the page and in your support list, and it never holds up anything else you are doing.

| Not built yet | State |
| --- | --- |
| Notify members in the Bynefit app | (Planned) |
| Notify members in your own app | (Planned) |
| Charge for your own services from your own site or app | (Planned) |
| Co-branded posters and share cards | (Planned) |
| QR code for your partner link | (Planned) |
| Custom app links for sign-in | (Planned) |

## Bring businesses to Bynefit

These are built and listed as Available in the Catalog. Bynefit switches the business features on for your program, so they appear once it has. The *Brand kit* page has ready-to-send copy under *Words you can use*: an announcement, an email, a social post, and plain explanations of how the loyalty program and free promotion posts work, so you can tell a business what to expect before you invite them.

| What | How it works | State |
| --- | --- | --- |
| Your partner link | A link that carries your partner code. Spaces that start from it are counted as yours. It is on your console home once switched on. | (Available) |
| Invite the businesses you bring | A signed request from your system invites a business owner. They claim it, and you see its status, never their details. Open *Businesses* in the console. | (Available) |
| Free promotion posts | Send a promotion for a business you brought. The owner approves it, and it appears in their Space feed. It costs neither side anything. | (Available) |
| Dues, event tickets and donations | Your own Space already takes these through Bynefit, paid online (with PayPal on the web) and listed in your payment records. | (Available) |

## Credits

Credit is set per partner by Bynefit. It accrues on Business Setup orders paid by a Space that carries your partner code, after the date the rate took effect and inside the tail period if there is one. It never raises what the customer pays. The Credits page of the console shows your terms and totals, and the totals are also in the [summary](https://bynefit.com/docs/partner-events#read-your-totals) response.

---

Source: https://bynefit.com/docs/partner-guide
Checked against the live API on October 10, 2026.