Sites and roles

Portland has an address, a phone number, opening hours and a set of preferences. Inside it, some people can see invoices and some can't. And Sarah doesn't call her customers "clients" — her staff say "households".

That's this module: the operational detail of a site, the roles inside it, the record of who changed what, and the vocabulary your staff see.

Before you start

• The module switched on for the site. If it isn't, everything below returns 403 regardless of your key — check the site's modules on the Locations page first.
• A credential with the right scopes — organizations.view to read.
• The site's id, for X-Location-Id on every request.

The endpoints

Site details and settings

Details are the site's own record — the things you'd print on an invoice. Read and change them like any resource.

Settings are a key-value bag, saved as a whole:

curl -X PUT "https://api.hyphabase.com/api/modules/organizations/locations/$SITE_ID/settings" \
  -u sk_live_xxx: -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"invoice_footer": "Thank you — Brightside Cleaning", "week_starts_on": "monday"}}'

Roles inside a site

These are permissions for people working in Portland — a cleaner who sees their own schedule, a coordinator who sees invoices too. Distinct from the dashboard roles that decide who can open a site or issue a key, which are set up by clicking: Staff and roles.

Roles hold module permission strings — the same clients.view / schedules.create names a key's scopes use. See Who can do what.

Assigning a role to a person is in the Staff module; defining the roles is here.

Who changed what

The audit log is the most underrated thing in this module. It answers "who deleted that customer" without a conversation.

curl -G https://api.hyphabase.com/api/modules/organizations/audit-logs \
  -u sk_live_xxx: -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  --data-urlencode "per_page=50"

tells you what you can filter by, generated from what's actually in the log — so build a filter UI from that rather than hardcoding options.

gives you counts, for a "recent activity" panel.

It's read-only, which is the point. Nothing in the API lets you edit or delete an audit entry.

Calling things what your staff call them

Sarah's team says "households", not "clients". Rather than making everyone translate, override the term.

lists every term you can rename;

sets one.

Two things to be clear about. This changes display labels, not the API — field names, endpoints and event types are unaffected, so your code still says clients. And it's per site, so Portland can say "households" while Salem says "clients", which is either a feature or a trap depending on how much you like consistency.

If you're building your own front end you may not need this at all — you control your own labels. It exists for the dashboard, and for anything reading labels from the API.

What you get told about

What to grant

organizations.view is safe for a publishable key — enough for a booking page to show a site's address and phone number.

organizations.update changes settings that other modules read, so it has wider reach than it looks.

What goes wrong

Recipes

Show your customers the right site details. Read the site's record and render its address and phone on a booking page. A publishable key with organizations.view is enough.

An activity feed. Poll audit-logs newest-first and render it. Drive the filter options from the filters endpoint so it stays right as the log grows.

Match the vocabulary your staff already use. Fetch language-terms, let an admin rename the handful that matter, and store overrides per site.

Next