The Worklio Embedded Payroll iFrames allow you to integrate the white-label solution within your existing platform.

1. Client Authorization Token

First, you need to get a "client" JWT token to be able to call the user token endpoint. You can obtain this client token with Client credentials authorization flow at /connect/token endpoint using the client_id and client_secret assigned to your application and user_token api scopes, like this:

2. User Token endpoint

The user token endpoint generates an output that is used to access the embedded payroll application on the client side. With the Client JWT token used as the Bearer token in the request header, you can make an API call to /token/user/ endpoint to obtain appUrl and userToken result.

The appUrl property contains the URL to the embedded payroll application and the userToken property is an authentication token in JWT format created on behalf of the user specified by the endpoint parameters.

This endpoint is called by the POST method and its content is generated based on parameters in the request body as a JSON object with the following properties:

  • email : The user's email for whom the token is to be generated; this token will contain user identifications (such as loginId and role/roleId) according to other parameters.
  • token : Instead of the "email" parameter, a "token" parameter can be used with the value of the user's authenticated JWT token from another trusted authentication server.
  • mode : Mode of the application container in which the generated token will be used. This is an optional parameter, if specified the mode will be included as a claim in the user token.
IntMode
1Browser
2Iframe
  • page : The type of page to be included as a claim in the user token:
IntPage NameAccessible for RolesRequired Properties
1Multi-Admin DashboardMulti-Admin
2Multi-Admin CompaniesMulti-Admin
3Multi-Admin PayrollsMulti-Admin
4Multi-Admin Payroll HistoryMulti-Admin
5Multi-Admin ReportsMulti-Admin
6App SettingsMulti-Admin
7Admins SettingsMulti-Admin
8NotificationsMulti-Admin
1001Company DashboardAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1002Company InfoAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1003Company TeamAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1004Company Team MemberAdmin, Multi-Adminemployee-id, company-id - if accessed as Multi-Admin
1005Company PayrollAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1006Company Payroll HistoryAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1007Company BenefitsAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1008Company ReportsAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1009Company Time OffAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1010Company IntegrationsAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1011Company Premium ATSAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1012Pulse SurveysAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
1013Time AttendanceAdmin, Multi-Admincompany-id - if accessed as Multi-Admin
10001Employee DashboardEmployee
10002Employee Personal InfoEmployee
10003Employee ContractEmployee
10004Employee Tax SetupEmployee
10005Employee DeductionsEmployee
10006Employee Pay StatementsEmployee
10007Company InfoEmployee
10008DocumentsEmployee
10009Time OffEmployee
10010Time AttendanceEmployee
  • roleAccess : Specifies the type of access control, determining which login role of the user will be selected for the user token; its values have the following meanings:
IntRole
nullselects the highest role from all existing user roles
1System
2Admin
3Employee
  • company <int>: For the login roles that a user may have been assigned more than one for different companies, it is possible to explicitly select a role for a specific company with this parameter.
    This is an optional parameter that applies to Client Admin and Employee roles.
  • customAppClaims array(type , value ): An array of application properties that are required according to the requested page.

Example:

curl --request POST
     --url /token/user/ \
     --header 'Authorization: Bearer ' \
     --header 'content-type: application/*+json' \
     --data '
     {
       "page": 4,
       "email": "[email protected]",
       "roleAccess": 2,
       "customAppClaims": [
         {
           "type": "employeeId",
           "value": "123"
         }
       ]
     }
     '

Endpoint output:

{
    "email": "[email protected]",
    "appUrl": "https://your_app_domain",
    "userToken": "eyJhbGciOiJSUzI..."
}

3. Embed iFrame Into Your Page

Finally, you can embed an iframe into your application using the appUrl and userToken properties, you received from the User token API call.

<iframe src="@Url.Content(appUrl+userToken)"></iframe>

Mode-Specific Behavior

Iframe Mode (mode: 2, default)

  • Navigation menu and user menu are hidden
  • User is locked to a specific flow or page
  • A link is available to return to the starting point if user navigates further
  • Ideal for embedding single-page features or custom flows in limited containers

Browser Mode (mode: 1)

  • Full application interface is available including menus
  • User can move freely across the platform
  • Logout option is not presented (use browser close or the Close link in the user menu in the app to exit)
  • Suitable for opening the full application at defined entry point in a new browser window or tab

❗️

If you try to access an iframe-only URL directly in the browser, you may receive an "Unallowed Flow Context" error. This is a protection mechanism to prevent loading restricted content outside its intended container.


Displaying Custom Flows in an iframe

WEP iframes support displaying specific sections of a page, not just the entire page. To achieve this, you need to include the appropriate flow value in the customAppClaims.

Supported Flows and Required Properties

Flow NameRequired Properties
custom-fields-employee-viewcompany-id, employee-id
custom-fields-employee-editcompany-id, employee-id
custom-fields-companycompany-id
custom-fields-employee-onboarding-phase1company-id, onboarding-id
custom-fields-employee-onboarding-phase2company-id, ercu
premium-atscompany-id
premium-ats-settingscompany-id

Example:

curl --request POST \
     --url /token/user/ \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/*+json' \
     --data '{
       "email": "[email protected]",
       "customAppClaims": [
            {
              "type": "flow",
              "value": "custom-fields-employee-view"
            },
            {
              "type": "company-id",
              "value": 1
            },
            {
              "type": "employee-id",
              "value": 1
            }
        ]
     }'

Configuration note

To successfully call a User token endpoint, you need to get the external client configuration for your application, the client_id and client_secretmentioned in the first chapter.

The URL for the application and API endpoints must also be properly configured for your instance environment.
This configuration is provided by Worklio and please contact us in case of missing or incorrect configuration.