Skip to main content

​
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

Anything defined in the Ramp API 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.
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.

​
Connect in Serval

1

Open the Ramp connect dialog

Add a new Ramp connection from your Serval integrations page. The dialog is titled Connect Ramp.
2

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.
3

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.
4

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.
5

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.
6

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).
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.

​
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.
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.”
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.
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.
Need help? Contact support@serval.com for assistance with your Ramp integration.