Client Authorization
SetldPay serves many clients — the businesses whose card programs run on the platform — from one shared system. Client authorization makes sure every request touches only the clients its caller is entitled to, and that every change is attributed to exactly one. This page is the business-level picture: who calls in, what they can see, what they can change, how trusted internal staff reach across all clients, and the guardrails that keep one client's data invisible to another.
Who Calls the Platform
Two kinds of caller, one shared idea — the credential carries the list of clients it may act for
Staff who sign in to the SetldPay Hub — a client's own team and SetldPay's internal teams alike. Their session knows which clients they belong to.
Software calling the platform directly with an API key — no person at a keyboard. The key carries the same kind of client entitlement.
Effective Client Scope
The set of clients a request is allowed to operate within — and how a caller narrows it down
Every request operates within the effective client scope — the set of clients its credential grants. Viewing and reporting span the whole granted set by default, so one page of results can pull from every granted client, side by side.
Granted three clients, the caller sees those three — and only those three.
Unless asked otherwise, a viewing request quietly fans out across every granted client. Transaction lists, merchant searches, audit trails — one combined view, each row labelled with its client, totals aggregated across the scope.
A caller can narrow to a single selected client — this is the Hub's client switcher: pick one, and every view filters to it for the rest of the session. The selection must be a client the credential already grants.
The Acting Client for Changes
Viewing can span many clients — but a change always belongs to exactly one
Reading can be broad; changing cannot. Anything that creates or modifies data — a merchant set up, a terminal updated, an agreement signed — must name exactly one acting client, and is attributed to that client alone.
Elevated Access — Reaching Across All Clients
A deliberate, cataloged permission — not a hard-coded back door
Some internal work needs to see across every client at once — a platform-wide investigation, a support query spanning accounts. A dedicated permission, client-scope expansion, lifts the effective scope from "my granted clients" to all clients. Initially only one role holds it: the SetldPay Super Admin.
With client-scope expansion, the granted-list limit falls away.
Every Record Knows Its Client
Combined views only work if every row says where it came from
Every record the platform returns is tagged with its owning client — a merchant, a terminal, a transaction — no matter which combined view it appears in. That tag lets the Hub show a client column, group results sensibly, and never leave a reader guessing whose data they are looking at.
The Guardrails
The promises that hold even when something goes wrong — isolation, non-disclosure, proof
clients are isolated by default
One client can never see another's data — unless a single credential was explicitly granted both. Sharing is deliberately handed out; it never happens by accident or proximity.
out-of-scope behaves as "doesn’t exist"
Reach for a record outside your scope and the platform answers as though it simply isn't there — the same answer as for something that never existed. Nothing leaks through the shape of a refusal.
isolation is tested automatically
Isolation isn't left to trust. Automated tests guard every type of resource, proving on every change to the platform that a caller scoped to one client cannot reach another's data.
every change is audit-logged
Each change records who did it and which client it was done for. Because a change names exactly one acting client (§02), the audit trail always answers what happened, for whom, by whom.
Four Requests, Start to Finish
Worked examples — the model in motion, from credential to result
A finance user whose credential grants Epipoli, TBS Europe and Touchwood opens the transactions list.
arrives she opens the transactions list — selecting nothing
Her credential carries all three clients; the request names none.
decide the platform reads the scope off the credential
Effective scope: the three granted clients. Nothing outside it exists for this request.
result one combined list comes back, every row tagged
Rows from all three clients, side by side; the total counts across the whole scope.
| merchant | amount | owning client |
|---|---|---|
| Riverside Café | €42.50 | TBS Europe |
| Stazione Nord | €18.00 | Epipoli |
| Harbour Books | €112.30 | Touchwood |
narrow she flips the client switcher to TBS Europe
The selected client narrows every view to one client for the rest of her session — same rules, smaller scope.
A partner's back-office system holds an API key granting two clients — Epipoli and TBS Europe — and submits a new merchant.
arrives the system submits a merchant — naming no client
The key grants two clients, but a new merchant needs a home — one client's catalogue, one reference namespace. The platform won't guess.
refused the request is turned away: which client?
Nothing is created. (A key granting exactly one client would have had it assumed automatically.)
retry the system retries, naming TBS Europe as the acting client
TBS Europe is in the key's grant, so the change proceeds — attributed to that client alone.
result created, owned, and on the record
A SetldPay support lead — SetldPay Super Admin, whose role carries client-scope expansion — chases a duplicate payment that could sit under any client.
arrives she searches transactions across the whole platform
No client selected — her own granted list might not cover where it landed.
expand client-scope expansion lifts the granted-list limit
The permission on her role lifts her effective scope to all clients — decided like every other request, just with a wider answer.
result the duplicate turns up — under a client she was never granted
The rows come back tagged as always. She sees them because the catalog says she may — not because anything was bypassed.
proof the reach itself is on the record
Her request is logged with its expanded scope. The catalog shows who can do this (§03); the logs show when it was done.
A caller whose credential grants only Epipoli asks for a TBS Europe merchant by its reference — a guess, or a stale bookmark.
arrives the caller asks for the merchant by reference
The reference is real. The merchant exists — under TBS Europe.
decide the platform checks the record against the scope
The owning client is outside the caller's scope — and out-of-scope must behave as nonexistent (§05).
answer the answer is simply: not found
Identical to the answer for a merchant that never existed. The caller learns nothing — not even that there was something to find.
The Whole Picture, in One Pass
From a caller arriving to a result going back — what the platform decides at each point
| the request is… | spans | names a client? | recorded as |
|---|---|---|---|
| Viewing / reporting lists, searches, exports, audit trails | whole granted set | optional — narrow to a selected client | read-only; nothing attributed |
| Creating / modifying merchants, terminals, agreements | one acting client | required — exactly one | attributed + audit-logged to that client |
| Elevated internal work platform-wide investigation | all clients | via client-scope expansion permission | same rules; the reach itself is auditable |