Security model
What your page can see, what it can never see, and what Payroo checks on every call. Share this with your security review.
What the host never sees
| Never in your page | Where it lives instead |
|---|---|
| Your partner credential | your server only; it authenticates POST /sessions and the server-to-server routes |
| Tax file numbers, bank account numbers, super member numbers | typed into secure fields, Payroo-origin iframes; your page receives { valid } and the runtime receives a single-use handle bound to one field of one record |
| Masked digits of those values | not even a mask leaves the frame |
| The confirmation of a bank change, approval, lodgement or payout | a Payroo-origin dialog your page cannot drive, pre-filled for the user, requiring their Payroo sign-in |
| The figures an approval commits to | the approval intent binds revision, totals and user; the Payroo-origin confirmation frame renders them from the server, not from your DOM |
| Payslip and payment file contents | opened through five-minute bearer links minted on demand |
| Webhook signing secret | returned once to your server |
Payroo staff, in turn, never see your credential value (a hash is kept), the webhook secret after the write, or a document link; the staff console works with identifiers and audited actions.
Sessions and tokens
- The session token is a compact ES256 signature over a session id, a token version and an expiry (
iss: payroo-embedded,aud: payroo-api), nothing else. It travels only inAuthorization: EmbeddedSession <token>; the runtime keeps it in memory and never writes it to storage, URLs, the DOM or events. Default lifetime 15 minutes, hard limit 8 hours with refresh. - Every call re-reads, with strong consistency, the session, your delegation to the company and your partner record, and enforces: session active and unexpired, token version current, partner active, delegation active, the route's scope in the session, the route's component in the session. A change at Payroo (a revoked credential, a suspended delegation) takes effect at the next request, not at the next mint.
- Employer sessions are minted only for a Payroo user who is an administrator of that company; the user's membership is re-checked on every call.
- Employee sessions carry only
self:*scopes. One created by an invitation exchange has no password behind it: the single-use, seven-day token is the assurance. - Bootstrap tokens (60 seconds, one component) let the Payroo frame document verify who may frame it; they carry no session.
Frames and origins
- The frame document is served by the Payroo API origin, verifies the bootstrap's ES256 signature against the published JWKS, and sets
Content-Security-Policy: frame-ancestorsto your registered origins per request. A page on an unregistered origin cannot frame it; a bootstrap for one component cannot open another. - CORS answers preflights only for origins registered on an active partner, with exactly the contract's headers.
hostOriginat mint must be one of your registered origins, exact scheme and host, no wildcard.
Writes
- Every mutation takes an
Idempotency-Key; a reused key with a different body is refused (422 idempotency_body_mismatch). - Pay run writes take
If-Match; a stale tag is refused (409 revision_conflict). - Saves that carry sensitive values run as a durable save command: the payload is validated without touching the handles, every handle is verified (unconsumed, unexpired, same session family, same company, right kind and target), the engine saves, and only then are the handles consumed together with the audit row in one conditional write. A failure consumes nothing; a retry with the same key is safe.
- Approval needs an intent bound to the revision and totals plus the user's step-up; lodgement needs the user's step-up and the explicit declaration; a bare session token can do neither.
Audit and data
- Every request is audited with actor type, operation, resource type and outcome, including refusals; you read a five-field projection per company; Payroo holds the full record, keyed by the
X-Correlation-Idyou receive. - Page events, webhook bodies, audit rows and status reads carry identifiers and states only; the runtime refuses to emit an event whose payload contains an amount, a TFN or an account number.
- Rate limits: 600 requests per minute per credential, 120 per session, fixed windows,
429 rate_limitedwithRetry-After. - Sandbox and production are separate records, credentials and data; nothing crosses.
Your obligations
- Keep the credential and the webhook secret on your server; rotate on Payroo's schedule; report a suspected leak at once.
- Mint sessions only for users signed in to your product, with truthful
assurance, the scopes and components the page needs, and the exacthostOrigin. - Treat the session token as a bearer secret for its lifetime: memory only.
- Register exact origins and keep your Content-Security-Policy allowing Payroo's frames (
frame-src) and, for the native shell, API calls (connect-src). - Do not attempt to read, set or mask sensitive values around the secure fields, and do not try to drive the confirmation dialogs.
- Verify every webhook signature against the raw body, process by event id, and keep the previous secret until
previousSecretUntilduring a rotation. - Open document links immediately and never store them.