Authentication

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:

Partner Authentication: Your platform is identified using a unique partner key.

User Authentication: Individual sessions are authenticated with JWT tokens generated using your private key.

This two-layer approach ensures both your platform and its users are properly authenticated and authorized. Your partner key is also used for server-to-server communication and for authenticating session that are not tied to a user session.

WARNING

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:

Your platform generates and maintains a private key

The corresponding public key is shared with Easyteam during onboarding

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.

Share the public key with your Easyteam integration manager while keeping the private key secure.

Creating JWT Tokens

JWTs must be generated on your backend and should include:

Employee and organization identifiers

Permission information and access role definition

Payroll information (Optional)

Example JWT Generation (Node.js)

Use your IDs for all communication with Easyteam and keep them consistent between runs. Find more details about using IDs here.

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)

Read more about integration with the Easyteam Embedded iframe here

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 here

💡

Work with your Easyteam integration manager to define custom permissions that align with your platform's role structure.

Testing Authentication

To test your authentication implementation:

Generate a JWT token using your backend code

Decode the token at jwt.io to verify correct payload

Use the token with Easyteam components in your sandbox environment

Check browser console for authentication errors

Next Steps

Generate your public-private key pair

Share your public key with your Easyteam integration manager

Implement JWT token generation on your backend

Test authentication with the Sandbox Environment

Explore component implementations in the UI Components Guide

💡

Need help with authentication? Contact our team for personalized implementation support.

Authentication Overview#

Partner Key Setup#

Public-Private Key Pair#

Generating Key Pairs#

Creating JWT Tokens#

Example JWT Generation (Node.js)#

Parameters#

Using Tokens with Integration Components#

With EasyTeamLauncher (Iframe)#

With EasyTeamProvider (React)#

Using Permissions#

Testing Authentication#

Next Steps#

Authentication Overview

Partner Key Setup

Public-Private Key Pair

Generating Key Pairs

Creating JWT Tokens

Example JWT Generation (Node.js)

Parameters

Using Tokens with Integration Components

With EasyTeamLauncher (Iframe)

With EasyTeamProvider (React)

Using Permissions

Testing Authentication

Next Steps