Skip to main content

Justworks 2.0

Visualize your Justworks company and workforce in the JupiterOne graph. Ingest the Justworks company/organization and its members — employees and contractors — mapping each member to the company and to their manager, and enriching members with job title, department, office, and employment details. Monitor your identity and org structure through queries and alerts.

Installation​

The Justworks integration ingests your Justworks company and workforce using the Justworks Partner API (https://public-api.justworks.com/v1). It reads your company/organization (/company) and members (/members) to build a graph of the company, its employees and contractors, and the manager relationships between them. Because JupiterOne is not a Justworks partner, this integration uses a customer-provided credentials model: you obtain your own OAuth application from Justworks and supply its credentials to JupiterOne.

Prerequisites​

  • A Justworks account with administrator access.
  • A Justworks OAuth application (client_id and client_secret). Creating an OAuth application for the Partner API is not self-service — you must request one from Justworks. See the Justworks Partner API documentation for details.
  • A refresh token obtained by completing the one-time OAuth authorization (see below). Justworks refresh tokens are valid for 30 days.
  • Access to JupiterOne with permission to configure integrations.

Obtaining Justworks credentials​

  1. Request an OAuth application from Justworks for your company and note the issued Client ID and Client Secret.
  2. Grant the application the read scopes this integration uses:
    • company.basic:read and company.detail:read — company profile, including the company legal name.
    • member.basic:read, member.detail:read, and member.employment:read — members, including their emails, manager, member type, and employment details.
  3. Complete the one-time authorization at https://payroll.justworks.com/oauth/authorize (OAuth 2.0 Authorization Code flow) to obtain an initial refresh token. JupiterOne exchanges this refresh token for short-lived access tokens at https://public-api.justworks.com/oauth/token.
note

Justworks refresh tokens expire after 30 days. If an integration instance is idle for more than 30 days, the refresh token expires and you must re-authorize to generate a new one and update the instance configuration.

Configuration in JupiterOne​

To install the Justworks integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Justworks. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Justworks account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • Your Justworks Client ID — the OAuth client ID issued by Justworks. This field is required.

  • Your Justworks Client Secret — the OAuth client secret issued by Justworks. This field is required.

  • Your Justworks Refresh Token — the refresh token obtained from the authorization flow above. This field is required.

  • Optionally, an API Base URL to override the default Justworks API endpoint (https://public-api.justworks.com/v1). Leave this blank unless instructed otherwise by Justworks or JupiterOne support.

Click Create once all values are provided to finalize the integration.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.