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 in Authorization: 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-ancestors to 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.
  • hostOrigin at 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-Id you 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_limited with Retry-After.
  • Sandbox and production are separate records, credentials and data; nothing crosses.

Your obligations

  1. Keep the credential and the webhook secret on your server; rotate on Payroo's schedule; report a suspected leak at once.
  2. Mint sessions only for users signed in to your product, with truthful assurance, the scopes and components the page needs, and the exact hostOrigin.
  3. Treat the session token as a bearer secret for its lifetime: memory only.
  4. Register exact origins and keep your Content-Security-Policy allowing Payroo's frames (frame-src) and, for the native shell, API calls (connect-src).
  5. Do not attempt to read, set or mask sensitive values around the secure fields, and do not try to drive the confirmation dialogs.
  6. Verify every webhook signature against the raw body, process by event id, and keep the previous secret until previousSecretUntil during a rotation.
  7. Open document links immediately and never store them.