Rippling API tokens: scopes, permissions and revocation

Key takeaways

• A personal API token reaches only what its scopes and its creator's permission profile both allow.
• Rippling revokes a token automatically when its owner is terminated or it sits unused for more than 30 days, and tokens can't be transferred.
• Narrowing the creator's profile doesn't revoke the token: it keeps returning 200s with fields withheld in __meta.redacted_fields.
• OAuth installs run on access tokens with an expires_in value (Rippling's example is 129,600 seconds), renewed with a refresh token.
• If the person who installed an OAuth app is terminated, every token tied to them is revoked and another admin has to reinstall.
• A revoked credential returns 401; an uninstalled app or a missing installer permission returns 403.

A Rippling integration that authenticated cleanly yesterday can fail today without a single code change on your side. The credential didn't break. It reached the end of a lifecycle you never mapped.

Get the model wrong and one of two things happens: the integration goes dark the day your customer offboards an employee, or it keeps returning 200s while quietly handing back less data than it used to, with nothing in the response to explain why.

A personal API token reaches only what its selected scopes and its creator's permission profile both allow, and Rippling revokes it once the owner is terminated or the token sits unused for more than 30 days, according to Rippling's API Tokens and Permissions guide (checked 2026-09-30; the page carries no publish date). An OAuth app install runs on its own clock, an access token renewed with a refresh token, and per Rippling's partner error guide it also depends on the person who installed it staying at the company.

This page separates the two models: who each is meant for, what sets its reach, what ends it automatically, and what that ending looks like in your API responses. The table below maps six events worth planning for to what each credential does.

Which Rippling credential is your integration using?

Before any rule about scopes or revocation applies, you need to know which of the two models you're holding, and which one Rippling intends for your situation.

Rippling's developer guidance draws that first line explicitly: API tokens are for customer and internal integrations, and App Shop partner apps authenticate with OAuth. If you're a vendor connecting many customers' Rippling accounts, Rippling's documented route is an App Shop listing with OAuth.

Both models trace back to one person, the token's creator or the app's installer. The OAuth install adds a second clock, the access token's own expiry. Either way, the first lever you control is the scope list.

Where API token and OAuth app scopes come from

Both models draw scopes from the same per-endpoint list, but who chooses them, and how much choice they get, diverges immediately.

Rippling's API scope reference lists each scope and the endpoints it unlocks. Private scopes exist for the data Rippling doesn't hand out by default, and as Rippling's App Shop scopes documentation states, requesting one needs a documented business case and Rippling's approval, with access kept deliberately limited even after that. For everything else, both models push toward the same discipline: request only the fields your integration reads or writes, since a customer can't grant part of your listing and a token creator can't grant more than their own profile covers. Choosing which employee fields to request is the same exercise regardless of which credential you're building against.

API Tokens and Permissions: the profile that narrows a token's reach

Take a token created with workers.read and compensations.read by someone whose profile covers the entire company, sensitive data included. It can pull pay data for every worker. Narrow that same person's profile to their direct reports and basic personal details, and the identical token, with the identical scopes, returns only their own team, with compensation fields withheld. Nothing about the token changed. The profile did.

Rippling's permission profile works on two axes that combine with a token's scopes at request time: how much of the company the profile covers, from the entire company down to direct reports, and what kind of information within that population is visible, from sensitive data down to basic personal details. Rippling applies a profile change to every token that person has created, and it can also change which scopes they're able to select.

That narrowing is never documented as revoking the token. Withheld fields come back null, and List workers names each one under __meta.redacted_fields, with a reason:

{
  "__meta": {
    "redacted_fields": [
      { "name": "date_of_birth", "reason": "Insufficient entitlements" }
    ]
  },
  "results": [
    { "id": "...", "status": "ACTIVE", "date_of_birth": null }
  ],
  "next_link": "..."
}

For a benefits or payroll product, a redacted date_of_birth quietly breaks age-banded rates and eligibility checks without a single error. So if a working integration suddenly returns thinner records with no 401 or 403 anywhere in sight, read __meta.redacted_fields and check the creator's profile before you assume the integration is broken.

What it looks like when an API token is revoked

Rippling ends a personal API token in three ways, and two of them happen without anyone touching the token:

• The owner is terminated. Rippling revokes the token automatically when the person who created it leaves the company.
• It goes unused for more than 30 days. Rippling revokes an idle token automatically.
• Someone revokes it by hand. A user with the Manage the API Tokens app permission can use Revoke and remove, which deletes the token, and Rippling emails the owner, API Token Admins, and Super or Full Admins.

In all three cases the next call returns 401 Unauthorized, and nothing refreshes it. A revoked token is gone, and someone still at the company has to create a new one. That's the opposite of a narrowed profile, which keeps the token alive and keeps returning 200s with fields withheld. Treat a 401 on a token that worked yesterday as a reauthorization event, not something to retry.

An OAuth install fails, expires and recovers on its own schedule, covered next.

How OAuth access tokens expire, refresh, and get revoked

An OAuth access token carries its own countdown, the expires_in value returned at issuance. Rippling's example response shows 129,600 seconds, 36 hours, but read the value from each response rather than hardcoding it. Before that clock runs out, your integration exchanges the refresh token at Rippling's token URL for a new access token, the same mechanism any OAuth 2.0 connection uses to stay alive.

Rippling's partner error guide gives a 401 two causes. The access token may have expired, which a refresh fixes. Or the person who installed the app has been terminated, which revokes every token tied to them; a refresh won't help, and another admin has to run the install flow again. A 403 means the installing user doesn't have permission for the endpoint. That can start mid-life if the installer loses the admin rights the app's data needs, and it's also what an integration gets after the customer uninstalls the app.

Revoking a refresh token is meant to take its access tokens down with it. RFC 7009, the OAuth revocation standard, says a server that revokes a refresh token should also invalidate the access tokens issued under the same grant, but calls that a should, and is explicit that cascading policy varies by server. Rippling's public docs don't state its own cascade behavior, so a request that still succeeds a few seconds after you revoke isn't necessarily a bug.

Build for the person-level events as reauthorization events. If a refresh call fails, or a working install starts returning 403, alert the customer and route another admin back through your install flow.

Designing a Rippling integration that survives one person leaving

Every trigger above traces back to a single account, whether that's the token creator or the installing admin. The design question is whether your integration expects that or gets surprised by it.

Token lifecycles are one constraint; Rippling's per-IP burst limit is the other thing every token shares, covered in Rippling API rate limits, pagination and query limits. And some data no token can reach, because Rippling's API has no scope for it: see where Rippling benefits, dependents and payroll data come from.

A unified API is bound by the same lifecycle. Bindbee's Rippling API connection authenticates with a token your customer's admin creates in Rippling, so the termination trigger above applies to it. The inactivity trigger plays out differently: a Production connector syncs every 24 hours, so a healthy connection keeps its token in use.

What changes is what you see when a credential dies. The connector moves to Relink Needed and stops syncing, and Bindbee sends a connector_sync_error webhook. Reads keep returning the last successful sync with a 200, so treat that webhook as the signal to pause decisions on that customer's data. The fix is a relink with new credentials, and the connector keeps its connector_token through it, so the Bindbee IDs you've stored stay valid. A narrowed permission profile is quieter: the sync still succeeds, with fewer fields, so compare field completeness between syncs.

If you want to see how Bindbee connections report sync status, take a look at the Rippling integration.

Frequently asked questions

Do Rippling API keys and tokens expire?

Rippling's REST API calls the customer credential an API token (some of its pages say API key). It has no fixed expiry, but Rippling revokes a token automatically when its creator is terminated or it goes unused for more than 30 days. A revoked token returns 401 Unauthorized.

What happens to a Rippling OAuth install when the installer leaves?

Rippling revokes every token tied to that person when they're terminated, so calls return 401 Unauthorized and a refresh won't recover them. Another admin at the customer has to install the app again.

Can a Rippling API token be transferred to another admin?

No. Rippling treats API tokens as personal credentials tied to the person who created them, so when that person leaves, another admin has to create a new token.

Who can revoke a Rippling API token?

A user with the "Manage the API Tokens app" permission can revoke any company token from Tools > Developer > API Tokens, using Revoke and remove. Revoking deletes the token, and Rippling emails the owner and admins.

Why is my Rippling token returning fewer fields than before?

The creator's permission profile was probably narrowed. Rippling applies a profile change to every token that person created, so the token keeps working and returns 200s with withheld fields listed in __meta.redacted_fields.