Hosted sites

Client portal API

How a practice's hosted site shows each client their own engagements, documents, messages and bookings, and how the practice's own staff run the same work from its own admin page. Every call uses the person's Sign in with Bynefit token.

Who can see what

A visitor's token never works on the admin routes: they need an active manager or admin role in the practice's Space. Bynefit staff have no special access either, unless the practice gave them a role.

Set up

1. Make a sign-in clientA manager of the practice's Space opens /dash/sites/oauth. The client belongs to that Space, which is how every portal call knows whose engagements to look in. See OAuth 2.0 / OpenID Connect.
2. Sign people inOn a Bynefit-hosted site, add the auth block to config.json. The kit signs people in, stores the tokens and refreshes them.
3. Call the portalSend the access token as Authorization: Bearer. Bynli.auth.accessToken() returns a fresh one.

The portal answers browsers on bynefit.com, on *.site.bynefit.com, and on a custom domain once it is verified on a live site. Anything else gets no cross-origin permission. There are no cookies: only the bearer token. Access tokens last an hour and refresh tokens 60 days; a revoked or expired token gets 401 invalid_token.

Your first call

curl https://bynefit.com/api/portal/engagements \
  -H "Authorization: Bearer ACCESS_TOKEN"

await Bynli.use('auth');
const token = await Bynli.auth.accessToken();

const res = await fetch("https://bynefit.com/api/portal/engagements", {
  headers: { Authorization: "Bearer " + token }
});
if (res.status === 401) { Bynli.auth.signIn(); }
const { engagements } = await res.json();

$ch = curl_init("https://bynefit.com/api/portal/engagements");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $accessToken],
]);
$data = json_decode(curl_exec($ch), true);
foreach ($data['engagements'] as $e) {
    echo $e['id'], ' ', $e['status'], ' ', $e['title'], "\n";
}

{
  "engagements": [
    {
      "id": "eng_0123456789abcdef0123456789abcdef",
      "kind": "service",
      "serviceKey": null,
      "entityType": null,
      "jurisdiction": null,
      "title": "Bookkeeping cleanup",
      "status": "info_needed",
      "paymentState": "awaiting",
      "totalCents": 45000,
      "items": [],
      "submittedAt": "2026-10-02 15:10:00",
      "closedAt": null,
      "updatedAt": "2026-10-09 11:42:18"
    }
  ]
}

The list is the client's own engagements at this practice, newest first, up to 50, drafts included. Items appear only on the detail call.

The engagement

Client routes

Bodies are JSON. Ids that are not the caller's own answer 404 {"error":"Not found."}, the same as ids that do not exist.

curl -X POST https://bynefit.com/api/portal/engagements/eng_0123456789abcdef0123456789abcdef/reply \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Here is the address you asked for."}'

const res = await fetch("https://bynefit.com/api/portal/engagements/eng_0123456789abcdef0123456789abcdef/reply", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + await Bynli.auth.accessToken(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ body: "Here is the address you asked for." })
});
const { engagement } = await res.json();

Self-serve company formation orders that a person places directly with Bynefit are not in these lists: only engagements created by a practice for its client are.

Practice routes

For the practice's own manager or admin. Every route answers 403 This account does not manage this practice. to anyone else. Bodies must be JSON objects. Actions marked admin need the admin role, not just manager.

Errors

What is not available

• Listing other clients' engagements from a client token, or from any page without a practice manager signed in.
• Reading engagements with an API key, or with a webhook. The nearest signal is a task.created webhook when a request or reply opens a follow-up task, and it does not carry the engagement.
• A scope for engagements. The portal does not check sign-in scopes: it checks that the token belongs to a client of the practice, and that the person is a customer of it (or, for the admin routes, a manager).
• A page you must write yourself. The portal kit draws both the client and the staff screens from these calls, or you can build your own.