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 refreshAfter passes (the last fifth of the lifetime). Your server may call POST /sessions/{sessionId}/refresh to 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 through POST /sessions/{sessionId}/bootstraps on your session; you do not call this yourself.
  • Revocation. DELETE /sessions/{sessionId} ends one session; POST /sessions/revoke ends every session of a user or a company (when the person leaves your product, for example). The next call on a revoked session answers 401 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).