Rippling API Guide: Architecture, Authentication & Data Access

Key takeaways

• Every Rippling REST call authenticates with a Bearer token: a customer-created API token or a partner's OAuth access token, each bound to one company.
• A token's scopes decide which endpoints it can call; the creator's permission profile decides which records and fields come back.
• Fields the creator can't see return null with a 200 OK and are named in __meta.redacted_fields; nothing errors.
• Customer API tokens have no fixed expiry, but Rippling revokes them when the creator is terminated or after more than 30 days unused.
• Requests are capped at 300 per IP address per 10-second window; crossing it locks that IP out for 10 seconds.
• List endpoints paginate by cursor: follow next_link until it's null, with limit capped at 100 on most endpoints.

A Rippling API token carrying every scope your integration requested can still come back missing half the fields on a user record. The request returns 200 OK. Nothing errored and nothing was denied; the data simply isn't there.

Grant the same scope to two different admins and you can get two different datasets back: one sees the whole company, the other sees only their direct and indirect reports. The scope alone doesn't decide the response.

This reference walks both credential paths and their lifetimes, the two-layer rule that decides what a token returns, the limits that govern reading at volume, and how to trace a failure back to the layer that caused it. It's written for engineers building a Rippling integration their customers will authorize, and every Rippling mechanic below was checked against Rippling's developer docs on 2026-09-30.

Which credential path does your integration need?

Rippling issues credentials along two paths, and they differ in who authorizes them, how long they live, and who they're built for.

A customer token goes in the Authorization header, as in this call from Rippling's docs:

curl -X GET 'https://rest.ripplingapis.com/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <api_token>'

Read expires_in off each partner token response instead of hardcoding 36 hours. It's what Rippling's current example shows, and Rippling doesn't present it as a fixed contract.

The redirect URI you register also has to match the one you send in the token request exactly, character for character. RFC 9700, the IETF's January 2025 update to OAuth 2.0 security best practices, requires authorization servers to compare redirect URIs by exact string match, with only localhost ports for native apps excepted, specifically to stop an authorization code from being redeemed somewhere it wasn't meant to go.

Versions are part of the credential too. Rippling ships breaking changes as dated versions (YYYY-MM-DD), and each API token stays on the version it was created with until its owner or an admin updates it or that version is deprecated. The Rippling-Api-Version header pins a version per request, so a newer version never applies to an existing token on its own.

Rippling's Help Center covers this ground too, but it sits behind a login. The developer docs are the version you can read, cite and link from your own documentation.

Which path you choose decides how you get a token. What that token can read is decided somewhere else.

What decides which records and fields a token can read?

A token's scopes decide which endpoints it can call. What it returns, record by record and field by field, comes down to a second layer: the permission profile of the user who created it. Rippling's HRIS guide splits that profile into a permission scope, such as "The entire company" or "Direct reports only", and an employment data access level, such as "View and edit all sensitive data" or "View all basic personal".

Restricted fields don't fail. The endpoint still responds 200 OK, the field is present in the schema, and list responses carry a __meta.redacted_fields array naming each withheld field with a reason such as "Insufficient entitlements". A null can also mean you didn't expand the related object: GET /workers?expand=employment,compensation is Rippling's own example.

Changes to a creator's permissions apply to every token that person has created. A profile edit inside Rippling can thin out a working integration overnight without anyone touching the token.

OWASP API3:2023, the current OWASP API Security Top 10 category for broken object property level authorization, is why this exists as a separate layer: authorization has to be enforced per field on an object a token is otherwise allowed to see, not only per object. That's the layer Rippling's redaction implements. If you're the one deciding which of a customer's fields your own product needs, that design problem starts from the same record-versus-field distinction.

How do you read a full dataset without getting locked out?

Rippling's list endpoints paginate with a cursor. Each list response carries a next_link; request that URL as-is, with the same Authorization header, until it comes back null. limit defaults to 50 and caps at 100 on most endpoints, and asking for more returns a 400, per Rippling's docs.

As currently documented, Rippling applies no endpoint-specific limits beyond these; the burst budget and the two complexity caps govern every call, and breaking a pagination, filter or expansion cap returns a 4xx. The limit is per IP, so if your sync runs several workers behind one shared egress address, they share a single 300-request budget. And because the counter resets to zero after the penalty, a burst that trips the lockout costs the same 10 seconds whether it was one request over or a hundred.

Capping expansion depth and filter nodes alongside the request count follows the principle OWASP API4:2023 sets for unrestricted resource consumption: a single request can be expensive without being frequent, and a rate limit alone doesn't catch that. If you haven't built cursor pagination against an API before, the mechanics are the same ones any keyset-paginated API uses, and the cursor is what keeps a mid-sync data change from making you skip or repeat a row.

What does each failure tell you?

Five symptoms cover almost every Rippling API failure, and each one points at a different layer: the credential, the scope, the creator's permission profile, or the rate limit.

RFC 9110, the current HTTP semantics standard published in 2022, defines Retry-After as the header a server uses to tell a client exactly how long to wait, in seconds or as a date, before trying again. Rippling's docs don't confirm whether its 429 responses include one, so the safe client honors Retry-After when present and otherwise waits out the documented 10-second window.

A minimal reader that follows next_link and handles the lockout looks like this:

import time
import requests

def read_all(url, token):
    headers = {"Authorization": f"Bearer {token}", "accept": "application/json"}
    rows = []
    while url:
        resp = requests.get(url, headers=headers, timeout=30)
        if resp.status_code == 429:
            wait = resp.headers.get("Retry-After", "")
            time.sleep(int(wait) if wait.isdigit() else 11)  # one second past the 10-second penalty
            continue
        resp.raise_for_status()
        body = resp.json()
        rows.extend(body.get("results", []))
        url = body.get("next_link")
    return rows

workers = read_all("https://rest.ripplingapis.com/workers?limit=100", TOKEN)

What changes when the connection runs through a unified API?

None of those layers disappear because you didn't build the connection yourself. A unified API still authenticates against Rippling with a real credential, and that credential still inherits whoever created it.

That holds for Bindbee too. Bindbee connects to 110+ HRIS, payroll, ATS and benefits systems through one API, Rippling among them. Here's what that does and doesn't change for Rippling:

• The credential still belongs to a person. Bindbee's Rippling API connection authenticates with a token your customer's admin creates, so that admin's permission profile still decides which records and fields come back, and the token is still revoked if they're terminated.
• The rate limit moves off your plate. Rippling's 300-request burst budget governs how fast Bindbee syncs and shows up as sync duration, not as a 429 in your code. Your reads against Bindbee are limited to 200 requests per minute per connector token.
• Pagination and retries are handled for you. The sync follows next_link and waits out lockouts, and you read Bindbee's synced copy in the same unified models it uses for every other HRIS.
• Freshness follows the sync. The default sync runs every 24 hours, adjustable per connection, and webhooks fire when a sync finishes, fails, or finds created or updated records.
• A dead credential gets announced. If the token is revoked, the connector moves to Relink Needed and Bindbee sends a connector_sync_error webhook.
• Benefits and dependents need the SFTP connection. Rippling's API has no scope for them, so Bindbee reads them through its Rippling SFTP connection.

Rippling's own developer docs remain the reference for its full scope catalogue, the write APIs and anything below this layer.

Whichever path issues the token, what it can reach was decided before your integration sent a request: by the scopes, and by the person who created it. If you'd rather not own the pagination, the retry logic and the per-system mapping yourself, Bindbee's unified API handles all three. Book a walkthrough of connecting Rippling through Bindbee.

Frequently asked questions

Does Rippling have a public API?

Yes. The Rippling REST API at https://rest.ripplingapis.com covers categories including HRIS, Organizational Data, Payroll, Time, Talent and Data, and every request authenticates with a Bearer token. Customers create API tokens in Tools > Developer > API Tokens; partners building App Shop integrations use an OAuth install.

Do Rippling API tokens expire?

They have no fixed expiry, but Rippling revokes a token automatically when its creator is terminated or it goes unused for more than 30 days. Ownership can't be transferred, so another admin has to create a new token.

Can you get benefits data from the Rippling API?

Rippling's published list of REST API scopes, checked on 2026-09-30, includes no benefits or dependents scope. Bindbee reads Rippling benefits and dependents through its Rippling SFTP connection instead.

What is the Rippling API rate limit?

300 requests per IP address in a 10-second window. Crossing it rejects every request from that IP for 10 seconds, and as currently documented there are no endpoint-specific limits.

Why does a Rippling API field come back null?

Either the token creator's access level doesn't cover that field, in which case list responses name it in __meta.redacted_fields, or the related object wasn't requested with expand.