> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Justworks
> Justworks is a PEO and HR platform for payroll, benefits, time off, and employee data. Serval connects to it with your own OAuth application so workflows can read and act on that data on demand.
## 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
| Capability | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow API access | Workflows can call any Justworks Public API operation on demand, covering company profile, members, payrolls, paystubs, payroll fees, deductions, time off, docs, and legacy ID translation. |
| Employee and company data | Read company details, departments, offices, member profiles, contact info, and employment history. With extra presets, also compensation, date of birth, sex, and Tax ID (SSN). |
| Payroll and paystubs | Read payroll runs, payroll fees, and paystub details (requires the Payroll & Paystubs preset). |
| Time off | Read time off policies, requests, and balances. |
| Deductions management | The only write preset: create, update, and cancel employee deductions (the Deductions preset's write scope includes read access). |
| Connection health checks | Four automated checks verify company info, member list, department list, and time off policy access after connecting. |
Anything defined in the [Justworks API](https://public-api.justworks.com/v1/docs) 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.
Go to [Justworks Integrations settings](https://secure.justworks.com/integrations) 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.
Add this redirect URI to your OAuth application: [https://svflow-auth-config.api.serval.com/justworks/oauth/callback](https://svflow-auth-config.api.serval.com/justworks/oauth/callback)
Self-hosted Serval deployments use [https://svflow-auth-config.api.\<your-domain\>/justworks/oauth/callback](https://svflow-auth-config.api.\<your-domain\>/justworks/oauth/callback) instead.
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.
You can give the application a name, logo URL, terms of service URL, and privacy policy URL. Justworks shows these on the authorization screen.
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
Find Justworks in the Serval app catalog (it is labeled Beta) and start the connection. A "Connect Justworks" dialog opens.
Required. The field shows the placeholder "Enter your OAuth Client ID". Paste the Client ID from your Justworks OAuth application.
Required. A password field with the placeholder "Enter your OAuth Client Secret".
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.
| Preset | Description | Justworks scopes | Checked by default |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------- | ------------------ |
| Company Information | Read company details, departments, and offices | company.basic:read, company.detail:read | Yes |
| Member Information | Read employee/member details and contact info | member.basic:read, member.detail:read | Yes |
| Employment Data | Read employment history and job information | member.employment:read | Yes |
| Time Off | Read time off policies, requests, and balances | time\_off:read | Yes |
| Payroll & Paystubs | Read payroll runs and paystub details | payroll:read, paystub:read | No |
| Compensation | Read pay rates, salary, and compensation details | member.pay:read | No |
| Deductions (Read & Write) | Manage employee deductions | deductions:write | No |
| Sensitive Member Data | Date of birth, sex, and Tax ID (SSN) | member.dob:read, member.sex:read, member.tax\_id:read | No |
| Company Bank Account | Read company bank account information | company.bank\_account:read | No |
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.
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:
| Check | What it verifies |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get Company Information | Serval can read your company profile (Company Information preset - company.basic:read). On success: "Successfully retrieved company information for: \[name]". On failure: "Unable to read company information from Justworks." |
| List Company Members | Serval can list employees - it samples one member (Member Information preset - member.basic:read). On success: "Successfully retrieved members list from Justworks (found \[number] member(s) in sample)". On failure: "Unable to list members from Justworks." |
| List Company Departments | Serval can read department details, which are part of the detailed company profile (Company Information preset - departments populate with company.detail:read). On success: "Successfully retrieved departments list from Justworks (found \[number] department(s))". On failure: "Unable to list departments from Justworks." |
| List Time Off Policies | Serval can read time off policies - it samples up to ten (Time Off preset - time\_off:read). On success: "Successfully retrieved time off policies from Justworks (found \[number] policy/policies)". On failure: "Unable to list time off policies from Justworks." |
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](mailto:support@serval.com)** for assistance with your Justworks integration.