Skip to main content

Ramp

Read Ramp cards, transactions, bills, users and departments for spend reporting and reconciliation.

Connect it with: API key. Ramp's own documentation: https://docs.ramp.com/developer-api/v1/authorization.

What agents can do​

Connect Ramp so the agents working your tasks can reach it. With it connected, they can:

  • Pull card transactions for a period and match them to receipts, vendors or departments.
  • List cards, their limits and holders to answer who can spend what.
  • Find bills awaiting approval or payment and report them.
  • Read users and departments to build spend reports by team.

Before you start​

  • A Ramp business account and a user with the Admin role, who can open Company > Developer.
  • Decide the scopes first: a client credentials token can only use the scopes ticked on the app.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Ramp​

Jaah connects to Ramp with an API key, not with a sign-in button.

Connect with an API key​

Find each value first:

  • Client ID: In Ramp, open Company > Developer and select Create New App (an Admin role is required). Name it Jaah, tick the scopes agents need under Scopes (for example transactions:read, cards:read, users:read, business:read), select Client credentials as a grant type and save. The client ID is on the app's page.
  • Client secret: Shown on the same app page in Company > Developer, next to the client ID. Copy it when it is shown: Ramp lets you regenerate it later, which ends the old one.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Ramp card.
  2. Name the secret and choose who can use it.
  3. Fill in Client ID, Client secret.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to Ramp with an API key, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah calls Ramp's API once (POST https://api.ramp.com/developer/v1/token) with the stored values, and shows whether Ramp accepted it, or which value Ramp refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: client_id, client_secret.

Tell the agent in your task description which secret to use, for example “use the Ramp secret org/ramp”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Ramp once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Ramp's side too, revoke or delete the key at Ramp.

Limitations​

  • Agents mint their own access token from the client ID and secret (POST https://api.ramp.com/developer/v1/token with the scopes they need); each token lasts 10 days and Jaah does not cache it.
  • Only Ramp production (api.ramp.com) is supported; a sandbox app at demo-api.ramp.com is rejected.
  • Ramp allows 200 requests per 10 seconds per address and 100 token requests per 10 seconds; agents that hit the limit are paused for up to a minute.
  • Some scopes (for example cards:read_vault) are reserved for approved Ramp partners and cannot be ticked on your own app.
  • Agents can do only what the connected Ramp account allows.

Troubleshooting​

Test says Ramp rejected the client secret (DEVELOPER_7012)

The client ID or secret is wrong, or the secret was regenerated. Copy both again from Company > Developer and select Replace.

An agent gets 403 from Ramp

The app lacks the scope that call needs. Tick it on the app in Company > Developer and have the agent mint a new token.

Test fails with a 400 that names the grant type

Client credentials is not enabled on the app. Edit the app in Company > Developer and add it under Grant types.

Still stuck? Select Test and read the result: it names the value Ramp refused and the status it answered.

FAQ​

Why does Ramp ask for a client ID and secret instead of a key?

Ramp issues short-lived tokens only. The ID and secret let an agent mint one whenever it needs it.

Does Test change anything in Ramp?

No. It asks Ramp for a token with no scopes, which can read nothing, and discards it.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Ramp account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.