Start here

Test mode

A test key lets you, or an AI agent writing your integration, call the real API and get real-shaped answers from sample data. Get a call wrong, write the same entry twice, send garbage: nothing reaches a real Space, nobody gets an email, and you are not charged.

1. Make a test key For your Space's information, open /dash/integrations/api-tokens, choose Create key, then Test. For the public directory, do the same at /dash/developers/keys. A test key is ready straight away, with any permission you tick, including changing your directory. No review.
2. Keep it in an environment variable Put it in BYNEFIT_API_KEY, the same place your live key will go later, so switching is one line.
3. Call the API as normal Same addresses, same headers, same answers. Only the data is pretend.

curl -i "https://bynefit.com/dash/api/v1/events?limit=2" \
  -H "Authorization: Bearer bapi_tk_test_YOUR_KEY"

const res = await fetch("https://bynefit.com/dash/api/v1/events?limit=2", {
  headers: { Authorization: "Bearer " + process.env.BYNEFIT_API_KEY },
});
console.log(res.headers.get("X-Bynefit-Mode"));
const { data, livemode } = await res.json();
console.log(livemode, data[0].id);

import os
import requests

res = requests.get(
    "https://bynefit.com/dash/api/v1/events?limit=2",
    headers={"Authorization": f"Bearer {os.environ['BYNEFIT_API_KEY']}"},
)
print(res.headers["X-Bynefit-Mode"], res.json()["livemode"])

HTTP/1.1 200 OK
X-Bynefit-Mode: test
X-RateLimit-Limit: 500

{
    "data": [
        {
            "id": "evt_test_0001",
            "type": "event",
            "event_type": "member.joined",
            "actor": {
                "id": "usr_test_0001"
            },
            "subject": {
                "id": "mem_test_0001",
                "type": "membership"
            },
            "created_at": "2026-10-01T06:00:00+00:00"
        },
        {
            "id": "evt_test_0002",
            "type": "event",
            "event_type": "form.submitted",
            "actor": {
                "id": "usr_test_0002"
            },
            "subject": {
                "id": "sub_test_0102",
                "type": "form_submission"
            },
            "created_at": "2026-10-01T00:00:00+00:00"
        }
    ],
    "next_cursor": "MjAyNi0xMC0wMSAwMDowMDowMHwy",
    "has_more": true,
    "livemode": false
}

How to tell a test key from a live one

Have your code check the header before it does anything it cannot undo, and stop if it ever sees test where it expected live, or the other way round.

What the sample data holds

The same sample data comes back every time, so a test you write today still passes next month. Filters, paging and errors work exactly as they do live.

None of it is about real people. Names are numbered, email addresses end in example.test, phone numbers use the 555 range, and websites end in example.org. A test key never returns your Space's records, not even its name. The one thing it looks up is a partner's list of registered event names, so a partner-events dry run can tell you which events it would accept.

What gets saved, and for how long

Writes are checked exactly like a live call: the same required fields, the same errors, the same status codes and the same response. What happens next is different.

• Each test key keeps up to 200 saved records. Past that, the oldest goes first.
• A saved record lasts 24 hours, and can hold up to 8 KB. A bigger one is refused with 413.
• Revoking or rotating a test key deletes everything it saved.
• Nothing a test key does sends an email or a push notification, fires one of your webhooks, takes a payment, or counts toward your plan.

curl -X POST https://bynefit.com/dash/api/resources \
  -H "Authorization: Bearer bapi_tk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sample Food Pantry","category":"food","website":"https://pantry.example.org"}'

curl "https://bynefit.com/dash/api/resources" \
  -H "Authorization: Bearer bapi_tk_test_YOUR_KEY"

const res = await fetch("https://bynefit.com/dash/api/resources", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.BYNEFIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Sample Food Pantry", category: "food" }),
});
const { id, livemode } = await res.json();
console.log(res.status, id, livemode);

What a test key cannot call

Some things have no sample data. A test key gets a clear refusal there, never real data:

{
    "error": "test_mode_unsupported",
    "message": "Test keys only work with sample data, and this endpoint has none. Use a live key here.",
    "livemode": false,
    "docs_url": "https://bynefit.com/docs/test-mode"
}

Limits

• Each test key has its own hourly allowance, separate from your live keys. The X-RateLimit-* headers show what is left, and a 429 carries Retry-After, just like live.
• A Space can have up to 5 test keys at once, and each person up to 5 developer test keys. They do not count toward your live keys.
• Test calls are free and are not shown in your usage.

Testing webhooks

Webhooks have their own test. On /dash/integrations/webhooks, choose Send test event on an endpoint. Bynefit posts a sample event to that address, signed with its secret exactly like a real delivery, and shows you the status code your server answered and how long it took. The details are on the Webhooks page.

Moving to a live key

1. Make a live key on the same page with the permissions your code used. Changing your directory needs a review for live keys; the Keys and review page explains it.
2. Swap the value of BYNEFIT_API_KEY. Nothing else in your code should change.
3. Throw away any sample ids you saved. They do not exist outside test mode.
4. Make one read call and check the response says X-Bynefit-Mode: live before you let anything write.
5. Revoke the test key when you no longer need it.

What exists and what does not

• Read community resourcesList and filter community resources with a developer key. JSON, cursor paging.Available
• Submit a resource for reviewPropose a new entry. A moderator reviews it before it goes live.Available
• Manage your directoryAdd, edit and remove your own entries. Try it straight away with a test key; a live key needs a review first.By approval
• Signed webhooksGet an HTTPS call when something happens in your Space. Each delivery is signed.Available
• Sign in with BynefitOpenID Connect with PKCE for your own site or app.Available
• Custom app links for sign-inA native app can return through its own reverse-domain scheme once Bynefit approves that scheme for your partner account.By approval
• Embed widgetShow your directory on any website with one script tag.Available
• Partner eventsPartners send their own product events from a page, a server or an app, and read the totals back. Bynefit turns it on per partner.By approval
• Hosted sites runtimeEvents, resources, media, forms and page views for a hosted site, with no key.Available
• Read and edit hosted site filesAn agent key lists a Space's sites and reads, replaces and deletes their files, with versions, secret scanning and a daily write ceiling. The key owner approves the permission.Available
• Create and manage formsAn agent key creates forms for a Space, changes their settings and fields, pauses them and deletes unanswered ones, with a daily write ceiling and a test mode. Registration forms and submissions stay out of reach. The key owner approves the permission.Available
• Engagement types and stagesA Space defines its own kinds of client work with ordered stages inside the existing statuses. Managers edit them on the Engagements page, and an agent key reads and manages them with a daily write budget and a test mode. The key owner approves the permissions.Available
• Secrets and secure requests for hosted sitesStore a site's keys encrypted, use them in secure requests and form webhooks, and stop them being published in a page.Available
• Client portal APIA signed-in client reads their own engagements, documents and messages; a practice manager runs the pipeline.Available
• Client portal kit for hosted sitesTwo HTML elements give a hosted site a client portal and a staff pipeline, drawn from the Space's engagement types, stages and forms, with no code of your own.Available
• Site host APIA WordPress site reports a connection test, visit counts and daily health with a signed site key.Available
• Engagements through an API key or a webhookRead engagements from your own server, or hear about a change, without a person signed in.Planned
• Shop, products and orders API for hosted sitesA documented, key-based way to read and update a hosted site's shop.Planned
• OpenAPI specAn OpenAPI 3.1 description of the v1 API, with the error envelope and security schemes, at /docs?format=openapi.Available
• Agent keysA key made for an AI agent: read-only to start, short-lived, test mode first, every call logged, and the owner approves anything more.Available
• Webhook test eventOne button sends a signed sample event to your URL, so your tool can learn the fields before anything real happens.Available
• Replay a past webhook deliveryA Space admin sends a logged delivery to the endpoint again, freshly signed and marked as a replay.Available
• Request id and docs link on every errorEvery error body carries an id to quote to support and a link to the page that explains it.Planned
• Test keys and a sandboxKeys that only touch sample data, ready at once with no review, so a first attempt cannot break anything.Available
• Idempotency-Key on writesRetry a v1 write without doing it twice: the first answer is replayed for 24 hours, per key.Available
• Status pageLive state, 90-day uptime and incident history for the API, sign-in, webhook delivery, the widget, hosted sites and email. Atom and JSON feeds.Available