# 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

*Diagram: Your web app shows the Salaxy payroll UI in an iframe. Your backend signs the user in and gets a Salaxy access token with a signed JWT. The iframe loads the payroll application from embed.palkkaus.fi with the token in the URL hash and calls the Salaxy API. (Purple: provided and run by Salaxy. Grey: built and run by you. Dashed: optional.)*

1. **The user signs in to your product** — with your own login. Your users do not sign in to Salaxy separately.
2. **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](https://code.salaxy.com/security/impersonation.md). Salaxy only accepts it if the user's account has authorised your product.
3. **Salaxy returns a short-lived user access token.** There are no refresh tokens: when it expires, repeat step 2.
4. **Your page puts the token into the iframe's URL**, in the **hash** (`#access_token=…`), on the first load only.
5. **The iframe loads the payroll application** and your design from `embed.palkkaus.fi` (`test-embed.` and `demo-embed.` for testing — see [Environments](https://code.salaxy.com/get-started/environments.md)). The design is selected with the `skin` URL parameter or, without it, by the company's [service model](https://code.salaxy.com/integration/service-models.md).
6. **The payroll UI calls the Salaxy API** with the token. Payroll logic, payments, Incomes Register and pension reporting all happen on Salaxy's side.
7. **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](https://code.salaxy.com/get-started/rest/index.md) and build your own UI, or the [MCP server](https://code.salaxy.com/get-started/agentic/index.md) for an agent.

## How a white label project goes

*Diagram: Six phases: agree, test set-up, build, design, integrate (optional), go live. (Purple: done together with Salaxy. Grey: your development work. Dashed: optional.)*

| 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](https://code.salaxy.com/countries/index.md).

## Technical guides

- [Quick start](https://code.salaxy.com/get-started/white-label/index.md) — the five-minute proof of life
- [Navigation](https://code.salaxy.com/white-label/navigation.md) — the built-in menu or your own
- [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md) — the embed URL and the iframe height
- [Designs](https://code.salaxy.com/white-label/designs.md) — your look in the payroll UI (formerly *skins*)
- [Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md) · [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md)
- Working example: [iframe tester](https://test-embed.palkkaus.fi/iframe-tester.html) · interactive [embedded demo](https://code.salaxy.com/embedded-demo) (current developer site, after sign-in)
