Appearance
How embedded white label works Finland
Draft
A first technical overview, drawn from the white label and security guides of the current developer site. The step-by-step guides are now on this site (see the end of the page).
Embedded white label puts Salaxy's payroll UI — a single-page application — in an iframe inside your product. You keep your product, your navigation and your users' sign-in; Salaxy runs the payroll. It has been used in production since 2018, on desktop and mobile browsers and in mobile apps through web views.
What runs where
- The user signs in to your product — with your own login. Your users do not sign in to Salaxy separately.
- Your backend asks Salaxy for a token for that user. It signs a short-lived JWT with the certificate you created in Salaxy and posts it to the Salaxy token endpoint — the impersonation flow for single sign-on. Salaxy only accepts it if the user's account has authorised your product.
- Salaxy returns a short-lived user access token. There are no refresh tokens: when it expires, repeat step 2.
- Your page puts the token into the iframe's URL, in the hash (
#access_token=…), on the first load only. - The iframe loads the payroll application and your design from
embed.palkkaus.fi(test-embed.anddemo-embed.for testing — see Environments). The design is selected with theskinURL parameter or, without it, by the company's service model. - The payroll UI calls the Salaxy API with the token. Payroll logic, payments, Incomes Register and pension reporting all happen on Salaxy's side.
- Optional: your backend uses the REST API for what happens outside the UI — creating customer accounts from your system, taking payments through your own payment channel, fetching accounting data.
Navigation is client-side routing inside the iframe. Either embed embedded-horizontal.html, which has Salaxy's own menu, or embed embedded.html and drive it from your own menu by changing only the part after # (for example #/payroll). Changing anything before the # reloads the application and ends the session.
What you build and what Salaxy provides
| You build | Salaxy provides |
|---|---|
| Your product, its header, menu and footer | The payroll UI, kept up to date — new features arrive without work on your side |
| Your users' sign-in | Payroll logic and compliance: tax, insurance, Incomes Register, pensions |
| Token issuing in your backend (signed JWT → access token) | The token endpoint; you create your certificate in the Salaxy web application |
| The page that hosts the iframe: sizing, loading indicator, session-expiry handling | Hosting of the payroll application on test, demo and production hosts |
| Your navigation choice — Salaxy's built-in menu or your own | Your design implemented in the payroll UI — colours, logo, fonts — from your visual design, as part of the partnership |
| Optional REST integrations: account creation, payment channel, accounting data | The REST API and the payroll engine behind it |
What you do not do: access the iframe's contents, change Salaxy's internal routing, or implement payroll logic yourself. If you need deep UI changes beyond the design, or control over the payroll components themselves, white label is the wrong fit — use the REST API and build your own UI, or the MCP server for an agent.
How a white label project goes
| Phase | What happens | Technical outcome |
|---|---|---|
| 1. Agree | Commercial terms (per-payslip pricing), the data processing agreement, scope: which payroll features your users get | Agreement; test access |
| 2. Test set-up | Get a test account and create your certificate. Embed test-embed.palkkaus.fi with a test token — the five-minute proof of life | The payroll UI running inside your page |
| 3. Build | Token issuing in your backend (step 2 above); the hosting page with sizing, loading and session-expiry handling; your navigation choice | Your users reach payroll through your own sign-in |
| 4. Design | You provide your visual design; Salaxy implements it in the payroll UI (the design, formerly called the skin) — included in the partnership and its integration support | The payroll UI looks like your product |
| 5. Integrate (optional) | REST API integrations: creating accounts from your system, your own payment channel, accounting data | Payroll connected to the rest of your product |
| 6. Go live | Production checklist: token issuing, token renewal, iframe height, session-expiry UX, final design. Switch to embed.palkkaus.fi | Live for your customers |
Availability
Embedded white label is available in Finland. For other countries it is not yet decided — they launch on MCP and skills.
Technical guides
- Quick start — the five-minute proof of life
- Navigation — the built-in menu or your own
- URL parameters and sizing — the embed URL and the iframe height
- Designs — your look in the payroll UI (formerly skins)
- Impersonation flow for SSO · Partner-initiated account creation
- Working example: iframe tester · interactive embedded demo (current developer site, after sign-in)

