Rippling OAuth Guide

This guide will help you set up your Rippling OAuth app to connect with Apideck.

Note: User needs to be logged in as a Partner Admin. To create an OAuth app in Rippling, you need to have Rippling App Shop.

Steps to Create and Configure Your OAuth App

Go to the Rippling Portal.
Sign in with your Rippling account.

2. Create OAuth App

Make sure you are in the "Managed Listings" section.
Click "Create a new listing" to start setting up your OAuth app.
Enter the name of the app. This name is for internal reference and not the display name users will see in the Rippling App Shop.
Now you can read the requirements shown for listing, after that you can click on "Continue" button below.
Your OAuth app is created with status "Draft".
In the Managed Apps section, find your app and click on arrow icon to the right of the app name that you created.
Next, click on the arrow icon to the right of the OAuth app in Listing Versions table.
You can configure the name, description, and other details for the app via sub-menus on the top. Note: The information you enter here will be shown in the Rippling App Shop.

3. Configure OAuth Redirect Flow

To handle Rippling's OAuth flow, you'll need to:

Create an endpoint in your application that will:
- Accept the OAuth callback from Rippling
- Generate a state parameter using Apideck's createCallbackState API
- Forward the request to https://unify.apideck.com/vault/callback with:
  - The code parameter received from Rippling
  - The generated state parameter

Example Node.js implementation:


app.get('/oauth/rippling/callback', async (req, res) => {
  const ripplingCode = req.query.code

  // Generate Apideck state
  const stateResponse = await fetch('https://unify.apideck.com/vault/callback-state', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${APIDECK_API_KEY}`,
      'x-apideck-app-id': '<YOUR_APP_ID>',
      'x-apideck-consumer-id': '<YOUR_CONSUMER_ID>' // If it doesn't exist, a new consumer will be created
    },
    body: JSON.stringify({
      redirect_uri: 'https://unify.apideck.com/vault/callback' // Or the redirect uri you want your user to be at the end of the oauth flow
    })
  })

  // Redirect to Apideck with code and state
  const apideckUrl = new URL('https://unify.apideck.com/vault/callback')
  apideckUrl.searchParams.append('code', ripplingCode)
  apideckUrl.searchParams.append('state', state)

  res.redirect(apideckUrl.toString())
})

Configure this endpoint URL in Rippling:
- Go to the "Integration" section
- Find the "Redirect" field
- Enter your callback URL (e.g. https://your-domain.com/oauth/rippling/callback)
- Click "Save Edits"

Rippling - Enter the Redirect URI

4. Add Your Scopes

In the "Integration" section, find the "Scopes" field.
Select the necessary scopes by clicking on the "+ Add a scope" button. Choose scopes based on the data your app needs to access (e.g., "employee" for employee information).
Be mindful to request only the scopes your app truly needs, as requesting excessive permissions may lead to scope rejection during the review process.

5. Add the Same Scopes in Apideck

Go to Apideck > Configuration > HRIS > Rippling
Ensure the scopes match those configured in Rippling.
Click on the "Save settings" button.

6. Obtain App Name, Client ID and Client Secret for Rippling Sandbox

In the "Testing" section, set up your Rippling Sandbox environment. This may take a few minutes to deploy.
Once deployed, navigate to the "Integration" section, click on the "Credentials" tab, and copy the App Name, Client ID, and Client Secret. 💡 TIP: Remember to save your App Name,Client ID and Client Secret securely. You'll need them for the connection.
Paste the Client ID and Client Secret in Apideck's Rippling app settings in "Client ID" and "Client Secret" fields respectively.
Click on the "Save settings" button.

7. Try Connection

Save your settings in Rippling.
In Apideck, click "Test Vault" to initiate the connection verification process.
Enter the App Name you copied earlier in the "App Name" field.
Attempt to connect to Rippling. If you encounter any issues, double-check all previous steps and ensure all information is entered correctly.

Note: Make sure to switch from Development dashboard to Rippling dashboard with Admin role to test the connection. Rippling - Switch to Rippling dashboard

8. Publish Your App

Once you have tested the connection and are ready to publish your app, click on "Submit for integration review" button.
Rippling team will review your app and get back to you.
Once approved, your app will be published and available in the Rippling App Shop.
After approval, update the client ID and client secret with the production credentials provided by Rippling.