For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
guide

API tokens and permissions

Create and manage API tokens in Rippling.

Use with AI:Rippling AI ChatGPT Claude Cursor

Overview​

Rippling’s REST API uses API tokens to authenticate requests and determine what data can be accessed. API token access is determined by two factors:

  1. The permission profile of the user who created the token.
  2. The API scopes selected during token creation.

While your permission profile may be granted access to certain information, you will also need to enable these same scopes when generating the API token in order to fetch this information. Consequently, if a user does not have permission to view certain data within Rippling, they will be unable to select specific scopes when creating an API token.

Since API tokens are generated with the permissions of the owner, a change to the owner's permissions can also change the scopes available to select within the API token.

Tokens are generated in the API credentials tab of the Developer app. Within API credentials, there are two permission levels: Manage the API Tokens app (admin) or Create and manage API Tokens.

CapabilityAdminCreate and manage API Tokens
Create and edit own tokens✅✅
View own tokens✅✅
View all company tokens✅❌
Edit other users’ token metadata✅❌
Revoke any token✅❌

We recommend granting admin permissions to your IT administrator or security team.

API tokens are Bearer tokens passed in the Authorization header:

Authenticated request
curl -X 'GET' 
'https://rest.ripplingapis.com/users'
-H 'accept: application/json'
-H 'Authorization: Bearer UOCgmwb.....'

Since each API token is associated with an owner, it is automatically revoked or expired if the owner is terminated or the token remains unused for over 30 days. You can refer to the Last accessed field to see when an API token was last used.

Key takeaways
  • API tokens inherit the permissions of their creator.
  • A token can only access data permitted by both the user’s permission profile and the token’s scopes.
  • Changes to a user’s permissions automatically applies to all tokens they've created.
  • Tokens are revoked if the owner is terminated or if the token is unused for more than 30 days.

Manage API tokens​

Create​

  1. Navigate to API credentials (Developer > API credentials).
  2. Click New API token. An API token requires the following fields:

FieldDescriptionAble to update after creation
NameA descriptive display name to communicate what the API token is used for.✅
Unique identifierThe unique identifier for the API token.❌
API versionThe version associated with the API token. API tokens using prior versions will stay on that version until either the owner or Admin updates the version, or the version is deprecated.✅
  1. Assign scopes to the API token.

If Custom Objects or Custom Object Records scopes are included during token creation, you will also need to select which object and record types the API token will be able to access (dependent upon your permissions). See this Help Center article for more information.

  1. Save the API token value after completing the creation flow. Note that you cannot view the API token again, so ensure you download or copy it at this point. Any request using the API token appears as the owner making the request, so please treat an API token as a password.

When an API token is created, a notification to the owner, API Token Admins, and company Super/Full Admins is sent for security purposes:

Subject: "New API token created for your organization"

New API Token email

Edit​

API token owners can add or remove scopes from an API token at any time. To edit an existing token:

  1. Go to Developer > API credentials.
  2. Click the three dots next to the token.
  3. Click Edit and update scopes as needed.
API token scopes can only be updated by the token's owner!

Rippling does not allow updating API scopes on tokens not created by the user. API token admins can update the Name and API version of other user's tokens.

Revoke​

Revoking an API token is a destructive action. It deletes the API token and attempting to use it again will result in an HTTP 401 Unauthorized error.

  1. Go to Developer > API credentials.
  2. Click the three dots next to the token.
  3. Click Revoke and remove, then confirm.

When the API token is revoked, an email notification is sent to the owner, API Token Admins, and company Super/Full Admins.

Subject: "An API token was revoked"

New API Token email


Permission use cases​

Below are example permission profiles and how you can provide the appropriate amount of access based on company needs.

If you are not familiar with Rippling permissions, please review the following Help Center articles:


FAQs​

Why am I seeing null values in responses?​

null values indicate the data exists but your API token does not have permission to view it.

Check:

  • The token owner’s permission profile.
  • The token’s enabled scopes.
  • Whether the required expand parameters have been included in the request.

Field-by-field rules for workers, users, and compensation are in Worker and user field access.

Insufficient OAuth scopes​

Insufficient oauth scopes to access ____ errors occur when an API request tries to access data or endpoints outside the API token’s scope or the user’s permission level.

Check:

  • The token owner’s permission profile.
  • The token’s enabled scopes.

Why is my response missing employees or records?​

API responses only include data the API token owner's permission profile is authorized to view.

For example:

  • Managers can only retrieve data for their direct and indirect reports.
  • Super Admins can retrieve company-wide data.

To expand access, update the user’s permission profile to include The entire company.

When API token creators are terminated, what happens to their API tokens?​

Tokens are automatically revoked.

Can ownership transfer when an admin offboards who created API tokens?​

No. Another admin must create a new API token.

Why isn't API token ownership transferred?​

API tokens are personal credentials tied to the person who created them, not company assets that can be reassigned. When that person is terminated, their tokens are automatically revoked so a former employee can't keep programmatic access to your Rippling data.