Skip to main content

Authorization

Follow this guide to create a new Rippling credential that will allow Nexla to authenticate to and exchange data with your Rippling account.
rippling_api_auth.png

Rippling

Prerequisites​

To connect Nexla to Rippling, you need a Rippling API token with the appropriate scopes for the data you want to access. API tokens are generated in Rippling's Company Settings by a Rippling administrator.

Rippling API Surfaces​

Rippling provides two API surfaces that Nexla uses:

  • REST API (rest.ripplingapis.com): The primary Rippling API for workforce data, including workers, departments, teams, compensations, legal entities, work locations, users, job requisitions, candidates, time entries, and custom objects. Uses Bearer token authentication and cursor-based (next_link) pagination.

  • Platform API (api.rippling.com/platform/api): An earlier API surface covering employees, leave requests, leave balances, leave types, custom fields, and company activity. Uses the same Bearer token with offset-based pagination.

Both API surfaces use the same API token. The scopes you assign to the token determine which endpoints are accessible.

Obtain a Rippling API Token​

Rippling API tokens are generated from Company Settings in the Rippling admin console. Only administrators with the appropriate permissions can create API tokens.

  1. Sign in to your Rippling account as an administrator.

  2. Navigate to Company Settings in the left navigation panel.

  3. Select API Access from the settings menu. This section displays all existing API keys and provides controls for creating new ones.

  4. Click Create API Key to open the token creation form.

  5. Enter a descriptive name for the API key (for example, Nexla Integration) so it can be identified later.

  6. Assign the required scopes to the token. Scopes control which Rippling data the token can access. Select the scopes that correspond to the Rippling data you intend to use in Nexla:

    • Workers data (List Workers, Get Worker by ID): workers:read

    • Departments (List Departments): departments:read

    • Teams (List Teams): teams:read

    • Compensations (List Compensations): compensations:read

    • Legal Entities (List Legal Entities): legal_entities:read

    • Work Locations (List Work Locations): work_locations:read

    • Users (List Users): users:read

    • Job Requisitions (List Job Requisitions): job_requisitions:read

    • Candidates and Applications (List Candidates, List Candidate Applications): candidates:read

    • Time Entries (List Time Entries): time_entries:read

    • Custom Objects (List Custom Objects, List Custom Object Records): custom_objects:read

    • Employees — Platform API (List Employees): included with standard employee read access

    • Leave — Platform API (List Leave Requests, Leave Balances, Leave Types): leave:read; note that leave data requires Rippling's Time & Attendance module to be enabled for the company

    • Company Activity — Platform API (Get Company Activity): company_activity:read

    You can only grant scopes that your own Rippling permission profile includes. If a required scope is not available in the token creation form, contact your Rippling administrator to ensure your account has the corresponding permissions before generating the token.

  7. Click Save to generate the token.

  8. Copy the generated API token immediately and store it securely. The token value is only displayed once and cannot be retrieved again after you close the creation dialog.

Important

Rippling API tokens expire after 30 days of inactivity. If a Nexla flow using this credential stops receiving data, verify that the token has not expired and regenerate it from Company Settings > API Access if necessary.

For additional information about API tokens and scopes, refer to the Rippling API Tokens and Permissions guide.

Create a Rippling Credential​

  • To create a new Rippling credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

API Token​

  1. Enter the Rippling API token you generated in the API Token field. The token is transmitted as a Bearer token in the Authorization header of every API request Nexla makes to Rippling. This field is required and stored securely in encrypted form.

    The credential is validated against the Rippling REST API upon saving. If validation fails, verify that the token was copied in full and that the token includes at least users:read scope, which is used for the connection test.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.