White-label payroll UI (iFrames)

Short answer: The white-label payroll UI is Worklio's hosted payroll application, embedded in your product with an iFrame. You get payroll screens without building them, and you brand them with your own logo, app name, support contacts, and colors. Your server requests a short-lived user token, and the iFrame opens signed in to a page or flow you choose.

If you want to design the payroll screens yourself, use the API or the component library instead. For how the three paths compare, see What is embedded payroll.

How it works

1. Get a client token. From your server, request a token with the OAuth 2.0 client credentials flow at {AuthUrl}/connect/token, using the scope user_token. Keep this token on your server. Credentials are issued per environment. See How to get API access.
2. Exchange it for a user token. Call POST {ApiUrl}/token/user/ with the client token as a bearer token. Specify the user (by email or token) and the page or flow to open. The response returns the app URL and a userToken.
3. Embed the application. Set the iFrame src to the app URL, with the user token in the URL fragment.
4. Listen for events. The iFrame sends postMessage events to your page, such as activity signals and, for named flows, height changes and user actions. See iFrame events (postMessage).

The full request fields, page names, flows, and worked examples are in Embedding the white-label UI (v2).

What the embedded UI looks like

In iFrame mode, the Worklio menu, logo, and user menu are hidden. The user stays on the page or flow you opened, with a "Back to starting page" link. The background is transparent, so you can place your own background behind the iFrame. To show navigation inside the iFrame, set the menu claim.

You can open pages for multi-admin, admin, and employee users, or named flows such as custom fields and onboarding.

What you can brand

Set branding through the API. Instance-wide settings apply across an instance (a group of managed companies). Company-specific settings apply to one company, set by companyId. Instance-wide settings may be overridden at the company level.

For request payloads, see the White-label API Guide. For the color settings (skin, primary and secondary colors, menu color, and shape), see Custom Colors Data Structure.

Pages in this section

Before you go live

• The mode parameter is being retired in March 2027. After that release, the UI always runs in iFrame mode, and a Worklio link opened directly in a browser tab shows Unallowed Flow Context. If you send "mode": 1 today, embed in an iFrame before then.
• Use page_name, not page. The integer page parameter still works but will be removed. See Migrating from v1 to v2.
• Use v2. The v1 guide is legacy.

Next steps

1. Get API access and test in the sandbox.
2. Follow Embedding the white-label UI (v2) to open your first page.
3. Set your branding with the White-label API Guide.