# 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

### 1. Login

- Go to the [Rippling Portal](https://app.rippling.com/app-vendor/app-listings/managed).
- 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.
  ![Rippling - Create a new listing](https://res.cloudinary.com/apideck/image/upload/v1729594253/docs/connectors/rippling/rippling-create-new-listing.png)
- 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.
  ![Rippling - Enter the name of the app](https://res.cloudinary.com/apideck/image/upload/v1729594336/docs/connectors/rippling/rippling-enter-app-name.png)
- Now you can read the requirements shown for listing, after that you can click on "Continue" button below.
  ![Rippling - Read the requirements](https://res.cloudinary.com/apideck/image/upload/v1729594838/docs/connectors/rippling/rippling-read-requirements.png)
- Your OAuth app is created with status "Draft".
- In the [Managed Apps](https://app.rippling.com/app-vendor/app-listings/managed) section, find your app and click on arrow icon to the right of the app name that you created.
  ![Rippling - Find your app](https://res.cloudinary.com/apideck/image/upload/v1729594558/docs/connectors/rippling/rippling-find-app.png)
- Next, click on the arrow icon to the right of the OAuth app in Listing Versions table.
  ![Rippling - Click on the arrow icon](https://res.cloudinary.com/apideck/image/upload/v1729594634/docs/connectors/rippling/rippling-click-arrow-icon.png)
- You can configure the name, description, and other details for the app via sub-menus on the top.
  ![Rippling - Enter the name, description, and other details for the app](https://res.cloudinary.com/apideck/image/upload/v1729594789/docs/connectors/rippling/rippling-enter-name-description.png)
  **Note**: The information you enter here will be shown in the [Rippling App Shop](https://www.rippling.com/app-shop).

### 3. Configure OAuth Redirect Flow

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

1. Create an endpoint in your application that will:
   - Accept the OAuth callback from Rippling
   - Generate a state parameter using Apideck's [createCallbackState API](https://developers.apideck.com/apis/vault/reference#tag/Connections/operation/createCallbackState)
   - 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:

```javascript
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())
})
```

2. 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](https://res.cloudinary.com/apideck/image/upload/v1729595027/docs/connectors/rippling/rippling-enter-redirect-uri.png)

### 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](https://platform.apideck.com/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.
  ![Rippling - Sandbox client ID and secret](https://res.cloudinary.com/apideck/image/upload/v1729595411/docs/connectors/rippling/rippling-sandbox-client-id-secret.png)
  **💡 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](https://platform.apideck.com/configuration/hris/rippling) 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.
  ![Rippling - Enter the App Name](https://res.cloudinary.com/apideck/image/upload/v1729595839/docs/connectors/rippling/rippling-enter-app-name-apideck.png)
- 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](https://res.cloudinary.com/apideck/image/upload/v1729595976/docs/connectors/rippling/rippling-switch-to-rippling-dashboard.png)

### 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 - Submit for integration review](https://res.cloudinary.com/apideck/image/upload/v1729596104/docs/connectors/rippling/rippling-submit-for-integration-review.png)
- 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](https://www.rippling.com/app-shop).
- After approval, update the client ID and client secret with the production credentials provided by Rippling.