Authentication and sessions
Three credentials exist in Payroo Embedded, and each lives in exactly one place.
| Credential | Holder | Header | Lifetime |
|---|---|---|---|
| Partner credential | your server | x-api-key: <value> |
until Payroo expires or revokes it |
| Embedded session | your page (in memory) | Authorization: EmbeddedSession <token> |
15 minutes by default (ttlSeconds 60 to 900) |
| Bootstrap token | the runtime, per frame | inside the frame URL | 60 seconds, single component |
Payroo staff hold a fourth kind, the staff session, for the /admin/* routes. A partner never holds one.
The partner credential
Payroo issues your partner record and its first credential; the value is shown once and Payroo keeps only a hash. Store it as a server secret (an environment variable of your backend). It authenticates POST /sessions, POST /employers, the operations routes, GET /employers/{id}/status, /audit, /usage and the /webhooks/* routes.
Rotation. Payroo issues a second credential with an overlap window; both mint until the old one's expiresAt, then the old one answers 401 credential_expired. Switch your secret inside the window and tell Payroo when you have. Compromise. Ask Payroo to revoke at once: the credential answers 401 invalid_credential from that moment, and every session it minted keeps running to its own expiry.
Never put the credential in a browser, a repository, a log or a URL. If it appears in any of those, treat it as compromised.
Minting a session
Your server calls POST /v1/embedded/sessions for a user who is signed in to your product. Every field is required except where noted.
| Field | Meaning |
|---|---|
employerId |
Payroo's organisation id, or ext:<externalEmployerId> with the id you gave at provisioning |
user.externalUserId |
your stable id for the person (up to 200 characters). On the first session for a company send user.email too: Payroo maps your id to the Payroo user with that e-mail inside that company; afterwards the id alone is enough |
sessionType |
employer (the company's admin: setup, employees, pay runs) or employee (one person's self-service; then employeeId is required) |
components |
the components the page will mount, from calendar, company-setup, employees, employee-self-onboarding, run-payroll, payrun-history, self-payslips. Must be enabled on your record |
scopes |
what the session may do (below). Must be within your record's maxScopes |
assurance |
how and when the user authenticated with you: method password, mfa, sso, unknown or invitation, and authenticatedAt |
hostOrigin |
the exact origin of the page that mounts components (https://app.example.com). Must be in your record's allowedOrigins |
locale, ttlSeconds |
optional; en-AU and 900 |
Response 201: sessionId, sessionToken, expiresAt, refreshAfter, frame (the frame document origin and the bootstrap endpoint), principal (who the session is for) and branding (your theme as Payroo resolved it). Pass the whole object to your page as is.
Employer sessions require the mapped Payroo user to be an organisation admin of that company; otherwise 403 user_not_member. The user's membership and your delegation are re-checked on every call, not only at mint.
Scopes
| Scope | Allows |
|---|---|
company:read, company:write |
company details, pay settings, bank account, ATO connection, readiness |
employees:read, employees:write |
employee list and records, invitations |
payruns:read, payruns:write, payruns:lodge |
pay runs, line edits and approval; payruns:lodge for the lodgement command and the payment file |
documents:read |
payslips and document links |
calendar:read |
the pay calendar |
self:onboarding, self:payslips |
an employee's own onboarding and payslips (employee sessions) |
status:read, audit:read |
the partner-credential reads of a company's status, audit and usage |
Ask for what the page needs and no more: a route outside the session's scopes answers 403 scope_missing; a component outside the session's components answers 403 component_not_in_session.
Refresh, extra frames, revocation
- Refresh. The runtime calls your session route again when
refreshAfterpasses (the last fifth of the lifetime). Your server may callPOST /sessions/{sessionId}/refreshto extend an existing session instead of minting a new one; only the partner that minted it may refresh it (403 not_owner). - Bootstraps. Secure fields and frame-shell components each run in a Payroo-origin iframe that needs a 60-second bootstrap token bound to one component (
componentId). The runtime requests them throughPOST /sessions/{sessionId}/bootstrapson your session; you do not call this yourself. - Revocation.
DELETE /sessions/{sessionId}ends one session;POST /sessions/revokeends every session of a user or a company (when the person leaves your product, for example). The next call on a revoked session answers401 session_revoked; the runtime shows a blocked state and asks your route for a new session.
Step-ups: what the user sees
Four actions need the user to confirm with Payroo directly, in a Payroo-origin dialog your page cannot drive: a bank account change (bank_change), a pay run approval (approve), a lodgement (lodge) and a payout (payout). The component opens the dialog, the user signs in to Payroo (AuthKit, pre-filled with their address; the first time they set a password through Forgot password or the invitation e-mail) and confirms; the component retries by itself. On the API this is 403 step_up_required with error.stepUp.authorizeUrl, then the retry carries X-Step-Up-Intent. A confirmation that took too long answers 410 step_up_expired; the component starts the action again. A pay run approval additionally needs an approval intent created in the confirmation frame (403 approval_intent_required when a bare session tries).
What the frame checks
The frame document is served by the Payroo API origin, verifies the ES256 bootstrap against the published JWKS (GET /.well-known/jwks.json), sets frame-ancestors to your registered origins per request, and refuses a bootstrap bound to another component. A page whose origin is not registered cannot frame it. Your Content-Security-Policy needs frame-src for the API origin; the native shell also needs connect-src for it (CORS answers only for registered origins, with the contract's headers: Authorization, Content-Type, Idempotency-Key, X-Correlation-Id, X-Step-Up-Intent, X-Approval-Intent, If-Match).
Idempotency and concurrency
Every mutation accepts Idempotency-Key (a UUID per attempt, the same one for a retry). A reused key with a different body answers 422 idempotency_body_mismatch. Pay run mutations require If-Match with the ETag you read (428 precondition_required without it, 409 revision_conflict when it is stale: reload and retry).