Rippling
The Rippling integration lets Una pull worker data, such as names, legal entity, department, employment type and compensation, straight from Rippling's REST API. Your headcount and payroll planning then runs on live HR data, and nobody has to export a spreadsheet.
The integration is read-only. Una only ever sends read (GET) requests to Rippling. It never creates, changes or deletes anything in your Rippling account.
This page is for the Rippling administrator who will create the API token on your side. It takes about 10 minutes.
Rippling's REST API isn't part of its core product. Rippling sells it as a separate add-on (the Rippling API SKU), so your subscription must include it before you can create an API token. If you don't have it, the API Tokens tab won't appear under Tools → Developer, or it will be locked.
Check with your Rippling account manager before you start. If you need to buy the add-on, allow time for that when you plan your Una go-live.
What it does
- Create an API token. You create a token in Rippling for Una to use.
- Assign permissions. You choose what data the token can read.
- Save the token. You copy the token value, which Rippling shows only once.
- Hand off. You send the token to Una securely.
Una then tests the connection, agrees with you which fields to bring in, and sets up the sync.
Before you start
You'll need:
- The Rippling API add-on on your Rippling subscription. See the note above.
- A Rippling account with Super Admin access, or a permission profile that covers all the data Una needs. See Who should create the token.
- A secure way to share credentials, such as a password manager or a secure vault link. You'll use it in Step 5.
Who should create the token
The person who creates the token matters, for two reasons:
- A token can never see more than its creator. In Rippling, each API token is linked to the user who creates it and inherits that user's permission profile. The token's permissions are a subset of the creator's. If the creator can't see salary data, for example, the sensitive-data permission won't even appear in their list.
- The token depends on its creator's account. Every request made with the token shows as that user in Rippling. If the creator later leaves the company or loses their admin access, the token loses that access too, and the sync stops.
Create the token as a Super Admin who is expected to stay in the role, such as a finance or HR systems lead.
Step 1 — Open the API Tokens page
- Sign in to Rippling.
- In the left navigation, under Platform, hover over Tools and select Developer.
- Open the API Tokens tab.
- Click Create API token.
Step 2 — Name the token
Fill in the three fields on the Create API token screen:
| Field | What to enter | Example |
|---|---|---|
| Name | A display name that says what the token is for. You can change it later. | Una Integration |
| Unique identifier | Rippling fills this in from the name, with no spaces. You can't change it after creation. | una_integration |
| API version | Leave it at the default. | 2024-08-01 |
Click Continue.
Step 3 — Assign permissions (scopes)
The Assign API permissions screen lists every scope your own permission profile allows you to grant. A scope controls which data the token can read.
Recommended: select all
Tick Select all at the top of the list, then click Continue.
We recommend selecting everything because it gets your integration live fastest. Rippling's worker records link to many other objects, such as the user, legal entity, department, employment type, compensation and teams. Una reads each of these to build out a worker's full record, and each one needs its own scope. If any scope is missing, the related fields come back empty or Rippling rejects the request with an insufficient scope error. Then the token has to be edited and the connection tested again, often more than once.
Even with every scope selected, Una only reads data. It never uses the write side of any scope.
If you select Select all: set custom object access to view only
Selecting all scopes includes the custom object scopes. Rippling then shows an extra screen, Specify access to custom object data, before you finish.
- Tick View records only.
- Leave Admin access, Edit records, Create records and Delete records unticked.
- Click Save.
Una only needs to read custom object records.
Minimum scopes, if your policy requires them
If your security policy doesn't allow you to select all, these are the scopes Una needs as a minimum:
| Scope | Why Una needs it |
|---|---|
workers.read | Core worker records: status, start and end dates, title, location |
workers.custom-fields.read | Any custom fields you've added to workers in Rippling |
workers.sensitive.personal.read | Compensation details such as base salary. Your token can only have this if you're a Super Admin. |
legal-entities.read | The legal entity each worker is employed by |
| The read scope under Compensation, Department, Employment type and Team | Details of each worker's compensation, department, employment type and team |
If you plan to use more of your Rippling data with Una later, select all now so you don't need to edit the token again.
You can change a token's permissions at any time without creating a new token. See Changing permissions later.
Step 4 — Copy and save the token
Rippling now shows the token value, which starts with RPKEY.
Rippling shows the token once and never again. Before you leave this screen, click the copy icon or Download token, and store the value in your password manager. If you lose it, you'll need to create a new token.
- Copy the token, or click Download token.
- Tick I saved the API token and understand that I won't be able to see or copy it again.
- Click Finish.
Rippling emails the token owner, the API token admins and your company's Super Admins to let them know a new token has been created. That email is expected, and you don't need to do anything about it.
Treat the token like a password. It gives access to employee personal and salary data.
Step 5 — Send the token to Una securely
Send the token to your Una integration contact through a password manager share or a secure vault link.
Don't paste the token into email, Teams, Slack, a meeting chat or a support ticket, and don't show it on a shared screen or in a recording. If that happens, revoke the token and create a new one. See Day-two operations.
What happens next
Once Una has the token:
- Una tests the connection with a request to Rippling's workers endpoint. A successful response confirms the token and its permissions work.
- You agree the fields. Una walks through a sample worker record with you, or compares it against a file you've already shared, and agrees exactly which fields to bring in. Fields Una doesn't need, such as social insurance numbers, aren't extracted.
- Una sets up the sync. Una builds the extract and agrees a schedule with you. Weekly is typical, and a regular schedule also stops the token expiring, since Rippling expires tokens after 30 days without use. You can also run the sync yourself whenever you know something has changed in Rippling. See Workflow activities → Integration.
Optional: test the token yourself
If you'd like to confirm the token works before you send it, run this from a terminal (Command Prompt or PowerShell on Windows 10 or later, or Terminal on macOS). Replace YOUR_TOKEN with your token.
curl -H "Authorization: Bearer YOUR_TOKEN" https://rest.ripplingapis.com/workers
A working token returns a JSON list of workers. An error message means something needs fixing. See Troubleshooting.
Day-two operations
- Changing permissions later. Go to Tools → Developer → API Tokens, open the token, and click Edit next to API permissions. Change the scopes and click Save. The token value stays the same, so you don't need to send Una anything new.
- Rotating the token. Create a new token as in Step 1 to Step 4, send it to Una securely, and revoke the old token once Una confirms the new one is in use.
- Changing the token owner. If the person who created the token is leaving or losing admin access, have another Super Admin create a replacement token before the change takes effect, and send it to Una.
- Inactivity expiry. Rippling expires an API token that goes unused for 30 days. A scheduled sync (weekly, for example) keeps the token active. If you only run the sync manually, run it at least once every 30 days. If the token expires, create a new one as in Step 1 to Step 4 and send it to Una securely.
- Revoking access. Open the token on the API Tokens page and revoke it. Una's access stops immediately.
Troubleshooting
There's no API Tokens tab under Tools → Developer, or it's locked. Your Rippling subscription doesn't include the API add-on. Contact your Rippling account manager to add it.
The workers.sensitive.personal.read scope isn't in the list. Your account doesn't have the privileges to grant it. Ask a Super Admin to create the token instead. See Who should create the token.
Rippling returns 401 Unauthorized. The token is wrong, incomplete or revoked. Check that the full value was copied, starting with RPKEY, with no spaces or line breaks. If it was lost or revoked, create a new token.
Rippling returns an insufficient scope error, or some fields come back empty. The token is missing a scope for related data, such as the legal entity or department. Edit the token's permissions, as in Changing permissions later, and select all, or add the missing read scope. You don't need a new token.
The token was lost before it reached Una. Create a new token and revoke the one you lost. Nothing is affected.
The sync worked before but has now stopped. First check whether the token has expired, which happens after 30 days without use. See Day-two operations. Otherwise, check whether the token's owner has left the company or had their permissions reduced, since the token inherits their access. Create a replacement token as another Super Admin.
For anything else, see Rippling's API Tokens and Permissions documentation or contact your Una integration counterpart.