Skip to main content

​
About Justworks

Justworks is a Professional Employer Organization (PEO) and HR platform that covers payroll, benefits, time off, and employee data. The Serval Justworks integration is currently in Beta. Each Serval connection maps to exactly one Justworks company, and Serval automatically names the connection after the company it finds during setup. Serval only ever talks to Justworks’s official API address (public-api.justworks.com). Authentication: Customer-provided OAuth 2.0 application. You supply your own Justworks Client ID and Client Secret, pick permission presets, and approve access in Justworks. Serval refreshes tokens automatically while the connection is in use - no manual token upkeep (see “Connection stops working after a long idle period” below for the one exception). Data sync: On-demand only. There are no background syncs, triggers, or webhooks. Workflows call the Justworks API when they run, and four automated health checks verify the connection.

​
What the Justworks integration enables

Anything defined in the Justworks API can be accessed through Serval.

​
Get your credentials

Serval connects using an OAuth application that you create in your own Justworks account. The application gives you a Client ID and a Client Secret, and it controls which permissions (scopes) Serval is allowed to request.
1

Open Justworks Integrations settings

Go to Justworks Integrations settings and create an OAuth application for the Justworks Public API. Per Justworks’s own API documentation, OAuth application creation is not self-service for every account - if you do not see an option to create one, ask the Justworks team or your Justworks representative to set one up. They will need your redirect URI (next step), the scopes you plan to use, and an application name.
2

Set the redirect URI

Add this redirect URI to your OAuth application: https://svflow-auth-config.api.serval.com/justworks/oauth/callbackSelf-hosted Serval deployments use https://svflow-auth-config.api.<your-domain>/justworks/oauth/callback instead.
3

Enable the scopes you plan to use

Enable every scope you intend to select in Serval (see the permission presets table below). A good baseline matches Serval’s defaults: company.basic:read, company.detail:read, member.basic:read, member.detail:read, member.employment:read, and time_off:read.
4

Optionally add branding

You can give the application a name, logo URL, terms of service URL, and privacy policy URL. Justworks shows these on the authorization screen.
5

Record the Client ID and Client Secret

Copy both values somewhere safe. You will paste them into Serval in the next section.
Treat the Client Secret like a password. Serval stores both values to refresh tokens on your behalf, never displays the Client Secret again, and only ever shows the Client ID back to you obfuscated.

​
Connect in Serval

1

Open the Justworks connect form

Find Justworks in the Serval app catalog (it is labeled Beta) and start the connection. A “Connect Justworks” dialog opens.
2

Enter your Client ID

Required. The field shows the placeholder “Enter your OAuth Client ID”. Paste the Client ID from your Justworks OAuth application.
3

Enter your Client Secret

Required. A password field with the placeholder “Enter your OAuth Client Secret”.
4

Choose Permission Presets

Under the “Permission Presets” header (“Select the permissions you need for your workflows”), the form explains: “Select the permissions your workflows will need. Make sure your OAuth application has these scopes enabled.” Check at least one preset; you can expand any preset to see the exact scopes it grants. A live counter shows “[number] permission(s) selected” - it counts individual scopes, not presets, so the four defaults show 6.
5

Connect and authorize in Justworks

The “Connect to Justworks” button stays disabled until both credential fields are filled and at least one preset is checked; submitting an incomplete form shows “Please fill in all required fields”. Once you click it, your browser is sent to Justworks (payroll.justworks.com) to sign in and approve access. Finish this within 10 minutes of clicking the button.
6

Confirm the connection

After you approve, Serval identifies your Justworks company and names the connection after it. The connection is now ready for workflows.
Justworks connections cannot be edited in place - there is no update form, and the connect form always starts blank rather than pre-filling saved values. To rotate the Client Secret or change permissions, update the OAuth application in Justworks if needed, then reconnect and re-enter the Client ID, the Client Secret, and your preset selections from scratch.
Keep the Company Information preset selected. Serval reads your company profile during setup to identify and name the connection, so connecting fails without company read access.

​
Verifying the connection

After connecting, Serval runs four health checks against your Justworks company: Failure messages also include a hint about the likely cause - see “What health check error hints mean” below.
All four checks can pass while a workflow still fails. The checks only exercise the four default presets (company, member, employment, and time off data). If a workflow needs payroll, paystubs, compensation, deductions, sensitive member data, or bank account access, those presets must be selected at connect time and enabled on your Justworks OAuth application - no health check covers them.

​
Gotchas and troubleshooting

Serval requests exactly the scopes your selected presets map to, and Justworks rejects or narrows anything your OAuth application does not have enabled. After authorization, Serval records the scopes Justworks actually granted, which may be narrower than what you selected. If a health check fails with a permissions error, you will see: “This may be due to missing OAuth scopes. Please check that your Justworks application has the required permissions.” Fix the scopes on the Justworks side, then reconnect.
During setup, Serval reads your company profile to identify and name the connection. If the authorized token cannot read company information (for example, the Company Information preset was unchecked, or the OAuth app lacks company scopes), the connection fails with this message. Keep the Company Information preset selected and ensure company.basic:read is enabled on your OAuth application.
The credentials you enter are held for only 10 minutes while you complete the Justworks authorization. If you click Connect but finish approving later than that, the connection fails with one of these messages. Start the connect flow again and complete the Justworks approval promptly.
Existing Justworks connections cannot be edited in place - there is no update form, and the connect form never pre-fills saved values. To change permission presets or rotate the Client ID or Client Secret: update the OAuth application in Justworks if needed, then run the connect flow again and re-enter both credentials and the presets you want. Have everything on hand before you start, since the authorization must finish within 10 minutes.
Per Justworks’s API documentation, access tokens are valid for 24 hours and refresh tokens for 30 days. Serval refreshes the access token automatically whenever a workflow or health check calls Justworks, so an active connection stays healthy indefinitely. If the connection goes completely unused for more than 30 days, the refresh token expires and calls start failing with authorization errors - reconnect to restore it.
Each failed check appends a hint to its “Unable to …” message:
  • Unauthorized (401): “The OAuth token may have expired or been revoked. Please reconnect your Justworks integration.”
  • Forbidden (403): “This may be due to missing OAuth scopes. Please check that your Justworks application has the required permissions.”
  • Not Found (404): “The requested resource was not found. This may indicate a configuration issue.”
  • Server error (500): “Justworks API is experiencing issues. Please try again later.”
  • Anything else: “Error: [details]”
Every preset grants read-only access except Deductions (Read & Write), which lets workflows create, update, and cancel employee deductions (write access includes read). Also note the scope hierarchy: company.detail:read includes company.basic:read, and member.detail:read includes member.basic:read.
Sensitive Member Data (date of birth, sex, and Tax ID, which is the SSN), Compensation, Payroll & Paystubs, and Company Bank Account are all unchecked by default. Only select them if your workflows genuinely need that data.
A connection is bound to a single Justworks company and cannot reach across companies. If you manage more than one company, connect each one separately.
Need help? Contact support@serval.com for assistance with your Justworks integration.