> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ramp

> Connect Ramp to Serval with OAuth so workflows can issue and manage corporate cards, invite and suspend users, and reach anything in Ramp's developer API.

## About Ramp

Ramp is a corporate card and expense management platform for finance automation. Serval connects to Ramp over OAuth 2.0 and gives workflows typed access to Ramp's entire developer API, plus built-in workflows for inviting and suspending Ramp users and two installable workflow bundles for card and user management. After you connect, the connection is identified by your Ramp business's ID and legal name, which Serval reads from Ramp as the final step of the handshake. Serval only ever sends your Ramp credentials to one host for this integration: api.ramp.com.

**Authentication:** OAuth 2.0 - either through Serval's own registered Ramp app (default: you approve on Ramp's consent screen, no setup on the Ramp side) or with your own Ramp developer app's Client ID and Client Secret (client credentials flow).

**Data sync:** On-demand only. There is no background sync - Serval calls Ramp only when a workflow runs, attaching a current access token to every call. Connections made with Serval's app refresh their token automatically near expiry. Connections made with your own Ramp app exchange your app's Client ID and Client Secret for a fresh token on every request, and older connections that stored a Client ID and Client Secret directly work the same way - the difference is whose credentials are used, not how often they are exchanged.

## What the Ramp integration enables

| Capability                           | Description                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generic Ramp API requests            | Workflows can reach every endpoint in Ramp's developer API - users, cards, departments, limits, transactions, bills, accounting, and more - typed end-to-end against Ramp's API schema. Ramp returns large result sets in pages, and the bundled list workflows walk every page for you.                                                      |
| User provisioning and deprovisioning | Built-in **Invite Ramp User** and **Suspend Ramp User** workflows send an email invite to a new user or look up an existing user by email and deactivate them. Five app access roles are supported: Admin, Employee, Bookkeeper, Guest, and IT Admin.                                                                                         |
| Card Management workflow bundle      | "Issue cards, manage spending limits, and control access to shared virtual cards in Ramp". Includes Issue New Ramp Card, Change Ramp Card Spend Limit, Get Ramp Card IDs and Limits For User, and Add Ramp User to Shared Virtual Card (each requiring installer approval by default), plus Search Ramp Spending Limits (no approval needed). |
| User Management workflow bundle      | "List, search, and manage users and department assignments in Ramp". Includes List All Ramp Users, List All Ramp Departments, Check User Email Exists in Ramp, and Search Ramp Departments (no approval needed), plus Update User Manager in Ramp and Update User Department in Ramp (installer approval by default).                         |
| Scoped permissions                   | The connect dialog offers Ramp's full scope catalog - 54 scopes spanning accounting, bank accounts, bills, cards, departments, limits, reimbursements, transactions, users, vendors, and more (read and/or write variants). Two are locked as required and you choose the rest, so the connection can touch exactly what you allow.           |

Anything defined in the [Ramp API](https://docs.ramp.com/developer-api/v1/overview) can be accessed through Serval.

## Get your credentials

Most teams need no Ramp-side setup at all: the default connection uses Serval's own registered Ramp app, so all you need is a Ramp admin who can click Approve on Ramp's consent screen. Creating your own Ramp developer app is only required if you want to bring your own credentials.

<Tabs>
  <Tab title="Serval's Ramp app (default)">
    Nothing to create. When you connect, Serval redirects you to Ramp's consent screen to authorize the scopes you selected, then completes the handshake automatically. Make sure the person connecting can authorize apps for your Ramp business.
  </Tab>

  <Tab title="Your own Ramp app">
    You'll create a Ramp developer API app and copy its Client ID and Client Secret. Ramp's official reference is the [Ramp Developer API overview](https://docs.ramp.com/developer-api/v1/overview).

    <Steps>
      <Step title="Open Ramp's developer settings">
        In Ramp, go to **Settings** > **Developer API** ([direct link](https://app.ramp.com/settings/business/developer-api)). You need Admin or Business Owner access.
      </Step>

      <Step title="Create the app">
        Click **Create New App**, name it (e.g. "Serval Integration"), accept the terms, and click **Create**.
      </Step>

      <Step title="Enable the Client Credentials grant type">
        Under **Grant types**, enable **Client Credentials**. This is the flow Serval uses with your own app - no redirect or callback URL is needed.
      </Step>

      <Step title="Enable scopes on the app">
        Under **Scopes**, enable every scope you plan to select in Serval. Ramp only grants the intersection of what the app allows and what is requested.
      </Step>

      <Step title="Copy the credentials">
        Copy the **Client ID** (it starts with "ramp\_id\_") and the **Client Secret** (it starts with "ramp\_sec\_").
      </Step>
    </Steps>

    <Warning>
      Don't forget to enable `business:read` on your Ramp app. Serval always reads your business information immediately after connecting, and the connection fails without it.
    </Warning>
  </Tab>
</Tabs>

## Connect in Serval

<Steps>
  <Step title="Open the Ramp connect dialog">
    Add a new Ramp connection from your Serval integrations page. The dialog is titled **Connect Ramp**.
  </Step>

  <Step title="Choose scopes">
    The **Scopes** field is required (marked with an asterisk). `business:read` and `offline_access` are locked and can't be deselected - hovering them shows "Required for the integration to function". A fresh connection also pre-selects `users:read`, `users:write`, `transactions:read`, `cards:read`, and `departments:read`; remove optional scopes inline or add more through the **Edit scopes** modal.
  </Step>

  <Step title="Keep at least one optional scope selected">
    On a first-time connection, the Connect button stays disabled until at least one scope beyond the two locked ones is selected - hovering the disabled button shows "Please select at least one optional scope to connect". Reconnecting an existing Ramp connection (which opens with its current scopes loaded) is exempt, and any missing required scopes are merged back in automatically.
  </Step>

  <Step title="Connect with Serval's app (default)">
    Click Connect. You're redirected to Ramp's consent screen to approve the requested scopes, then returned to Serval, which finishes by reading your business's ID and legal name from Ramp.
  </Step>

  <Step title="Or use your own Ramp app">
    Open the three-dot menu next to Scopes and choose **Use your own Ramp app**. The form header reads "Using your own Ramp app" with the description "Authenticate with your Ramp app's client credentials"; the **Use Serval's app** link takes you back to the default flow. Enter your **Client ID** (placeholder "ramp\_id\_...") and **Client Secret** (placeholder "ramp\_sec\_..."). Both are required and whitespace is trimmed; submitting with either blank shows "Please provide both Client ID and Client Secret, or disable advanced mode." No Ramp consent screen appears for this path - that's expected.
  </Step>

  <Step title="Confirm the connection">
    A successful connection is labeled with your Ramp business's legal name (or the business ID, if your business has no legal name on file).
  </Step>
</Steps>

<Note>
  If your organization has disabled the Serval-managed OAuth option, the connect dialog shows the Client ID and Client Secret fields directly instead of behind the three-dot menu.
</Note>

## Verifying the connection

The Ramp connection ships with three built-in health checks:

* **Read Ramp Business Information** - confirms the connection can read your business's name, ID, and active status. Success: "Successfully retrieved business information for: \[name]". Failure: "Unable to read business information from Ramp."
* **List Ramp Users** - confirms the connection can list users and reports how many it found. Success: "Successfully listed \[number] users from Ramp". Failure: "Unable to list users from Ramp."
* **List Ramp Cards** - confirms the connection can list cards and reports how many it found. Success: "Successfully listed \[number] cards from Ramp". Failure: "Unable to list cards from Ramp."

Failure messages append a status-specific hint - see the gotchas below for the exact text.

<Tip>
  If the business information check passes but the users or cards check fails, your token is valid - the connection is just missing the matching scope (such as `users:read` or `cards:read`). Reconnect with those scopes selected, and if you brought your own Ramp app, make sure the same scopes are enabled on the app in Ramp.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The Connect button is disabled">
    A first-time connection requires at least one scope beyond the locked `business:read` and `offline_access` pair - hover the button to see "Please select at least one optional scope to connect". Reconnecting an existing connection is exempt: it can keep a scope set containing only the required scopes, and required scopes are merged back in if missing.
  </Accordion>

  <Accordion title="Connecting fails right after authorizing">
    Immediately after getting a token, Serval reads your Ramp business's ID and legal name to finish the install - in both auth modes. With Serval's app, a failed read produces an error that lists the scopes Ramp actually granted and notes "This usually means the 'business:read' scope is missing." With your own Ramp app, Serval surfaces Ramp's raw error response from the business lookup instead. Either way, the usual fix is making sure `business:read` is granted - for a bring-your-own app, enable it on the app in Ramp's developer settings.
  </Accordion>

  <Accordion title="A scope you selected doesn't seem to work">
    Requested scopes are an ask, not a grant - Serval stores whatever Ramp actually granted in the token response. When using your own Ramp app, the scopes enabled on the app cap what can be granted: a scope selected in Serval must also be enabled on the Ramp side, or it silently won't be included.
  </Accordion>

  <Accordion title="No Ramp approval screen appears when using your own app">
    That's by design. Connections made with your own Ramp app always use the two-legged client credentials flow, so there's no redirect, no consent screen, and no callback URL to configure on your Ramp app. If the credential exchange fails, Serval surfaces Ramp's raw error response so you can see exactly what Ramp rejected.
  </Accordion>

  <Accordion title="Health check failures include extra hint text">
    Failure messages append a hint based on the error Ramp returned: an authentication failure adds "The Ramp authentication token is invalid or expired. Please reconfigure the integration."; a permissions failure adds "The Ramp app may not have the required permissions. Check your OAuth scopes and permissions."; a not-found response adds "The requested resource was not found. This may indicate missing permissions or incorrect configuration."; and a Ramp server error adds "Ramp returned a server error. This is likely a temporary issue with Ramp's API - please try again later."
  </Accordion>

  <Accordion title="Default scopes differ depending on how the connection was made">
    The connect dialog pre-selects the required pair plus `users:read`, `users:write`, `transactions:read`, `cards:read`, and `departments:read`. A connection created without any scopes supplied (including legacy installs with no stored scopes) instead defaults to `business:read`, `users:read`, `users:write`, and `offline_access`. If a connection can do less than you expect, check which scopes it actually holds and reconnect with more.
  </Accordion>

  <Accordion title="Older connections keep working">
    Ramp connections created before the current connect flow stored the Client ID and Client Secret as custom integration data. They are still supported - every time a workflow runs, Serval exchanges those stored credentials for a fresh access token. No migration is needed.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Ramp integration.