Learn how to implement secure authentication for your Easyteam Embedded integration.
This guide will walk you through the process of generating and using JWT tokens with public-private key pairs.Authentication Overview#
Easyteam uses two primary security mechanisms:1.
Partner Authentication: Your platform is identified using a unique partner key.
2.
User Authentication: Individual sessions are authenticated with JWT tokens generated using your private key.
Never expose your partner key or private key in client-side code. Always generate JWT tokens on your backend services.
Partner Key Setup#
Your partner key is a unique identifier provided by the Easyteam team during onboarding. This key identifies your platform when communicating with Easyteam's APIs.Public-Private Key Pair#
Easyteam uses asymmetric cryptography (public-private key pairs) to secure communication:1.
Your platform generates and maintains a private key
2.
The corresponding public key is shared with Easyteam during onboarding
3.
JWTs signed with your private key are verified by Easyteam using your public key
Generating Key Pairs#
You can generate a new key pair using OpenSSL:Note: Don’t set a passphrase.
Creating JWT Tokens#
JWTs must be generated on your backend and should include:1.
Employee and organization identifiers
2.
Permission information and access role definition
3.
Payroll information (Optional)
Example JWT Generation (Node.js)#
Remember Easyteam does not store any private information about your users and businesses so always include anonymized IDs.Parameters#
| Key | Type | Description |
|---|
| employeeId | string | Your employee ID used to identify the session user. |
| locationId | string | Your location or site ID associated with the current session. |
| organizationId | string | Top-level entity ID (e.g. merchant or business group). |
| partnerId | string | Your Easyteam Partner ID (assigned to your platform). |
| payrollId | string | Optional payroll-specific employee ID used for payroll system sync. |
| employerPayrollId | string | Optional payroll-specific employer ID. |
| accessRole.name | string | Role label defining permissions scope (e.g., "admin", "manager"). |
| accessRole.permissions[] | string[] | List of permissions for this session. Read more in Permissions. |
| role.name | string | Display role name such as "Cashier", "Assistant", or "Manager". |
| role.hourlyWage | number | (Optional) Override the default hourly wage for this role. Specified in hundredths of currency (e.g., 1000 = $10.00). |
| wage | number | (Optional) Session-level wage override. Same format as above (e.g., 1000 = $10.00). |
| wageType | string | Type of wage being used. Typically "hourly" or "salary". |
| features.geolocation | boolean | Enables or disables geo-fencing restrictions for clock-in/out actions. Defaults to false. |
| features.shiftNotes | boolean | Enables or disables the ability to leave notes on shifts. Defaults to false. |
| features.<FEATURE> | boolean | Enable or disable other experimental or beta features. Defaults to false. |
Using Tokens with Integration Components#
Once you've generated a JWT token, you can use it with Easyteam's components.With EasyTeamLauncher (Iframe)#
With EasyTeamProvider (React)#
Using Permissions#
Permissions are included in the JWT and define the permissions for the current session. You'll have to include Easyteam-based permissions, read about the different options hereWork with your Easyteam integration manager to define custom permissions that align with your platform's role structure.
Testing Authentication#
To test your authentication implementation:1.
Generate a JWT token using your backend code
2.
Decode the token at jwt.io to verify correct payload 3.
Use the token with Easyteam components in your sandbox environment
4.
Check browser console for authentication errors
Next Steps#
1.
Generate your public-private key pair
2.
Share your public key with your Easyteam integration manager
3.
Implement JWT token generation on your backend
4.
Test authentication with the Sandbox Environment
Need help with authentication? Contact our team for personalized implementation support. 