Integrate with GreytHR
Connect GreytHR to JumpCloud to automate user provisioning and lifecycle management using HR data. As employees join, change roles, or leave, JumpCloud creates, updates, and suspends their accounts. This reduces manual account management and helps keep access aligned with HR changes.
Read this article to learn how to configure the GreytHR integration with JumpCloud’s Custom API Import connector.
To learn more about Custom API Import connectors, see Integrate with HR Directories (Custom API Import).
Prerequisites
- A JumpCloud administrator account
- JumpCloud SSO Package or higher or SSO à la carte option
- A GreytHR administrator account with permission to create API users and generate API credentials
- Your GreytHR company domain (for example,
yourcompany.greythr.com) - GreytHR API Client ID and Client Secret for an API user with read access to employee data
- Detailed GreytHR REST API documentation for the endpoints used in the integration (greytHR API v2)
Important Considerations
- Some GreytHR tenants require greytHR Implementation or Support to enable API user access before administrators can create credentials. If API Users is unavailable in Settings > Account Settings, contact greytHR support.
- GreytHR is configured in JumpCloud as a Custom API Import integration. There is no GreytHR prebuilt integration.
- Partial custom API import configurations are not saved even if the application is saved.
- The timestamp in the User Import Complete email is UTC.
- An SSO configuration for GreytHR is recommended, but not required for this import integration.
- Required mappings are externalId, email, and username.
- Every GreytHR API request requires the
x-greythr-domainheader with your company domain.
Configuring GreytHR API credentials
To create a GreytHR API user and generate credentials
GreytHR generates a password for the API user you create. The API user and password are the Client ID and Client Secret for the integration with JumpCloud.
- Sign in to your GreytHR Admin portal as an administrator.
- Go to Settings > Account Settings > API Users.
- Click Create API User.
Some GreytHR tenants require greytHR Implementation or Support to enable API user access before administrators can create credentials. If API Users is unavailable in Settings > Account Settings, contact greytHR support.
- Enter a User Name and Description.
Use a description that helps you easily identify this as the API user for the JumpCloud integration.
- Under Select Roles, select Employee API.
- Click Next.
- Copy the user name and system generated password. These values will be the Client ID and Client Secret for the integration.
The Client ID and Secret (token) may only be shown once. Copy them to a secure location, like the JumpCloud Password Vault, for future reference.
- Click Done.
- Note your company domain (for example,
yourcompany.greythr.com). You will need this value when configuring the Token Delivery Extra headers and Endpoint Configuration Additional headers in JumpCloud.
Creating a new JumpCloud Custom Application Integration
- Log in to the JumpCloud Admin Portal.
If your data is stored outside of the US, check which login URL you should be using depending on your region. If your organization uses LDAP, RADIUS, or requires firewall allow list configuration, the Fully Qualified Domain Names (FQDNs) will also be region specific. See JumpCloud Data Centers for the URLs, FQDNs, and IP addresses.
- Go to Identity Management > HR Directories.
- Select Create Custom Application.
- Click Next.
- Select Import users from this app (Identity Management) to configure user imports.
- Click Next.
- Enter the name for your integration in the Display Label field.
- Optionally, clear Show this application in User Portal if you do not want the integration to appear in the User Portal.
- Click Save Application.
- Click Configure Application.
Users are implicitly denied access to applications. See Authorize Users to an SSO Application.
Configuring the Custom API Import integration
Reference the greytHR API v2 documentation for authentication and employee endpoints.
- On the Provisioning tab, expand Configuration Settings.
- Select Custom API Import for API Type.
- Select or enter the following:
Authentication
- Under Authentication method, select OAuth 2.0.
- Under Grant Type, select Custom Token Endpoint.
- Under Token Request, enter the following values:
- Token URL:
https://api.greythr.com/oauth2/v2/client-token - Client ID: paste the API user from GreytHR
- Client Secret: paste the API user password from GreytHR
- Client Authentication: select Basic (Header)
- Leave Grant type and Scopes blank. Do not add additional token request parameters.
- Token URL:
- Under Token Delivery, configure how JumpCloud sends the access token:
- Header Name:
ACCESS-TOKEN - Header Value Format: Token (raw)
- Header Name:
- Turn on Advanced settings and verify the values for the following fields:
- Token Path:
access_token - Expires In Path:
expires_in - Error Code Path:
error - Error Message Path:
error_description - Leave Fallback lifetime (seconds) and Refresh Buffer (seconds) blank.
- Token Path:
- Under Extra headers, click + Add Header and enter the following values:
- Key:
X-Greythr-Domain - Value: your GreytHR company domain (for example,
yourcompany.greythr.com) which you copied when configuring the GreytHR credentials. Do not includehttps://.
- Key:
Optionally, turn on Sensitive Value to mask a secret header value.
You can add a maximum of five additional headers.
Endpoint configuration
Select or enter the following:
- Under Additional Headers, click + Add Header and enter the following values:
- Header Name:
X-Greythr-Domain - Header Value: your GreytHR company domain (for example,
yourcompany.greythr.com) which you copied when configuring the GreytHR credentials. Do not includehttps://.
- Header Name:
- Base URL:
https://api.greythr.com - Set Resource location to
data. - Under List users, verify or enter the following values:
- Method:
GET - Endpoint path:
/employee/v2/employees
- Method:
- Under Pagination, select or enter the following values:
- Pagination Type: Page-Based
- Page parameter:
page - Page Size Parameter:
size - Start index:
0 - Limit value:
50
- Under Total Count, select or enter the following values:
- Response Parameter Location: Body
- Response Body JSON Path:
pages.totalPages
- Click Test Connection to verify the credentials and configuration.
- If the connection test succeeds, expand Import Attribute Mapping and click Edit.
You can share the error message(s) with greytHR support to troubleshoot authentication or header issues.
User Schema Attribute Mapping
User Schema
This integration supports attributes from the following GreytHR Employees API endpoints. No other endpoints are currently supported.
| Endpoint | Attribute or Attribute Path Prefix | Example |
|---|---|---|
/employees | N/A | |
/employees/{id}/categories | providerUser.categories | providerUser.categories.categoryDesc |
/employees/{id}/org-tree | providerUser.org-tree | providerUser.org-tree.level |
/employees/{managerId} | providerUser.manager | providerUser.manager.email |
To Map Attributes
- Expand Import Attribute Mapping and click Edit to open Edit Attribute Mappings.
- At a minimum, the Required Mappings must be configured:
- externalId -
employeeId - email -
email - username -
email
- externalId -
- Once you are satisfied with the attribute mappings, click Update.
See the Mapping Table section below for suggested mappings.
Mapping Table
Select Direct in the Type column for a field name. Select Expression for an EXPR expression. Use + Add Attribute to add an optional attribute. To remove optional mappings, select the trash icon.
Optional source fields can be empty. They are automatically removed on activation and update.
Before activating the integration, use Preview Mappings to confirm the Returned from Service Provider fields and the JumpCloud Schema with Applied Mappings values before activation.
These mappings are provided as examples and reflect common use cases. We recommend reviewing and customizing the mapping logic to ensure it aligns with your specific business workflows, data environment, and security standards.
| JumpCloud Attribute | Service Provider | Type | Notes |
|---|---|---|---|
| Required Mappings | |||
externalId | employeeId | Direct | GreytHR employee ID. |
email | email | Direct | Work email from the employee list. Required for import. |
username | email | Direct | If email is entered, the integration automatically removes the ‘@’ and the email domain. |
| Optional Mappings | |||
firstname | firstName | Direct | Dedicated first-name field shown in the employee response. |
lastname | lastName | Direct | Dedicated last-name field shown in the employee response. |
displayname | name | Direct | Optional mapping; verify name in your preview. |
employeeIdentifier | employeeNo | Direct | Employee number. |
phoneNumbers_workCell | mobile | Direct | Work mobile when populated. |
department | len(filter(providerUser.categories ?? [], (#.categoryDesc ?? '') == 'Department')) > 0 ? (filter(providerUser.categories ?? [], (#.categoryDesc ?? '') == 'Department')[0].valueDesc ?? '') : '' | Expression | Selects valueDesc from the Department entry in categories. Returns an empty string when absent. |
jobTitle | len(filter(providerUser.categories ?? [], (#.categoryDesc ?? '') == 'Designation')) > 0 ? (filter(providerUser.categories ?? [], (#.categoryDesc ?? '') == 'Designation')[0].valueDesc ?? '') : '' | Expression | Selects valueDesc from the Designation entry in categories. Returns an empty string when absent. |
managerEmail | (providerUser.manager?.email ?? '') | Expression | Uses the manager email when present; otherwise returns an empty string. |
Expressions
You can use EXPR expressions to manipulate the information before storing it in JumpCloud. Read Use Expressions in JumpCloud to learn more.
To preview Mappings
Use this option to verify that the values that will be stored in JumpCloud based on the defined attribute mappings are what you expect. The Returned from Service Provider section shows what is returned by GreytHR. The JumpCloud Schema with Applied Mappings shows what will be stored in JumpCloud based on the attribute mappings.
- From the main Provisioning page, click Preview in the Import Attribute Mapping section.
- From Edit Attribute Mappings, click Preview Mappings below the mapping table.
- Optionally add query parameters supported by GreytHR to return certain records and click Update Preview.
- For example, GreytHR supports filters such as
state=CURRENTorstatus=<code>on the employees endpoint. See the greytHR API documentation.
- For example, GreytHR supports filters such as
- Click Close.
- Edit the mappings as needed.
- Repeat these steps until the results meet your requirements, then click Update to apply the mappings.
Check the GreytHR documentation to verify that filters are supported and which ones can be used if they are supported.
To activate the Integration
Do not click Save before clicking Activate. You will lose all of your configuration settings.
- Click Activate on the Provisioning page.
- If successful, a confirmation message appears and the status changes to Provisioning Active.
- Perform your initial manual import and verify the imported attributes.
- After verifying the initial import and any lifecycle mappings, configure scheduled imports if required.
Importing Users into JumpCloud
To import users from the JumpCloud Admin Portal
- Create a new application or select it from the Configured Applications list.
- Select the Provisioning tab and expand Import Users.
- There are several settings available for importing users from your custom application to JumpCloud.
To configure import settings
The selected Allow reactivation of users and Apply Advanced Filters settings will apply to both manual and scheduled imports.
- Allow reactivation of users on update for manual and scheduled imports - optional setting that allows suspended users to return to Active when the configured source state mapping resolves to ACTIVATED. Verify the state mapping before enabling this option.
Most organizations leave this setting disabled.
- Apply Advanced Filters on import (optional) - see your SP’s API documentation for available filters.
- Start Manual Import - kicks off the process flow for doing an immediate and one-time import of users from the SP to JumpCloud.
- Import Results - takes you to Directory Insights for User Imports.
To start a manual user import
Terminated users are not imported into JumpCloud.
- Expand the Import Users section and click Start Manual Import.
- Select one of the following options:
- Import new users and user updates
- Only import new users
- Only import user updates
- View and select specific new users to import (updates not supported)
If the option selected includes user updates, the following will occur:
- Any and all changes made to the mapped user attributes in the source application will be made in JumpCloud.
- Users whose State mapping resolves to SUSPENDED are automatically suspended in JumpCloud.
- If Allow reactivation of users on update is checked, suspended users in JumpCloud whose State mapping resolves to ACTIVATED have their user state changed back to Active in JumpCloud.
- Click Continue.
- If you selected View and select specific new users to import (updates not supported):
- Select the users you want to import.
Trial accounts can import up to 300 users and will be prompted to upgrade to a paid subscription after 30 days. The import stops once the limit is reached. Similarly, accounts managed by an MSP that have a license limit are only allowed to import users up to their license limit and will be prompted to contact their provider once that limit is reached.
- The count of users to be imported will show at the bottom left hand of the list. If this is correct, click Import.
- Review the information in the results modal.
- Click one of the tiles to go to the Users page, User Groups page, or Device Groups page, or close the modal.
If you close this modal, you will return to the Provisioning configuration panel.
- You will receive a User Import Complete email with a summary of the import results and a link for downloading a copy of the import results.
- You can now connect users to all their JumpCloud resources. Learn more in the Authorize Users to an SSO Application and Connect New Users to Resources articles.
Imported users must be members of a user group bound to an application for JumpCloud to manage their identity in and access to the application.
To schedule an import
Imports can be scheduled to run automatically. Enable scheduled imports only after validating the initial manual import.
- Turn on Schedule imports of users and user updates from GreytHR.
- Optionally enable Receive summary email after each scheduled import.
- If enabled, a User Import Complete email will be sent after each scheduled import. Enable this option for the first few scheduled imports to verify the results.
- Select Hourly, Daily, or Custom for your import schedule.
- If you select Custom, a new section appears:
- Repeat - how often the import will run:
- Hourly at a specific minute - select the time under At
- Daily - select the time under At
- Twice a day - select the time under At (first run) and At (second run)
- Weekly - select the day of the week under On and select the time under At
- Monthly - select Day of the month and select the time under At
- Timezone - timezone where you are located
- Repeat - how often the import will run:
- If you select Custom, a new section appears:
- Click Save Schedule when finished.
GreytHR API reference values
Use these values to match the demonstrated configuration. Replace {yourcompany}.greythr.com with your GreytHR company hostname.
| Setting | Value |
|---|---|
| Token URL | POST https://api.greythr.com/oauth2/v2/client-token |
| Token request auth | OAuth 2.0 > Custom Token Endpoint; Basic (Header) |
| Access token response field | access_token |
| Token header on API calls | ACCESS-TOKEN: {access_token} |
| Domain header | x-greythr-domain: {yourcompany}.greythr.com |
| List employees | GET https://api.greythr.com/employee/v2/employees |
| Resource location | data |
| Unique identifier | employeeId |
| Total Count > Response Body JSON Path | pages.totalPages (demonstrated configuration) |
| Page Parameter / Start index | page / 0 |
| Page Size Parameter / Limit value | size / 50 |
Optional list filters documented by GreytHR include:
state- ALL, CURRENT, or RESIGNEDstatus- employee status code from GreytHR System settings > General > List Of Valuescategory.{category}- for example,category.location=BangaloremodifiedSince- filter by last modified time
Removing the Identity Management Integration
- Log in to the JumpCloud Admin Portal.
- Go to Identity Management > HR Directories (or open the GreytHR custom application from Configured Applications).
- Search for the GreytHR application that you’d like to deactivate and click to open its details panel.
- Select the Provisioning tab.
- Scroll to the bottom of the configuration.
- Click Deactivate.
- Click Save.
- If successful, you will receive a confirmation message.
Was this information helpful?