OAuth 2.0

This guide walks you through the process of obtaining an access token via OAuth 2.0 protocol.

Ramp API uses the OAuth 2.0 protocol to handle authorization and access control. Currently Ramp supports two grant types -- Client Credentials and Authorization Code.


Which grant types should you use?

  • If you are a Ramp customer and your application only access your own Ramp data, then you can use both Client Credentials and Authorization Code
  • If your application is used by other Ramp customers, then you need to use Authorization Code

Authorization Code Grant

There are three parties involved in the Authorization Code -- the client (your application), the server (Ramp) and the user (data owner);

As an overview, the flow has the following steps

  1. Your application sends the user to authenticate with Ramp
  2. The user sees the authorization prompt and approves the app’s request for data access
  3. The user is redirected back via a redirect_uri with a temporary authorization code
  4. Your application exchanges the authorization code for an access token
  5. Ramp verifies the params and returns the access_token
  6. You application gets a new access_token with the refresh_token

Now let's walkthrough all the steps

step 1: user authenticates with Ramp

To start the Authorization Code flow, your application need to direct the prospective user to authenticate with Ramp by making a request in your browser to https://app.ramp.com/v1/authorize with the following required query parameters

response_typeMust be set to code
scopeA space-separated list of scopes granted to the returned token,. e.g if you only wish to use the token to read transactions, the scope should be set to transactions:read.
Note that you cannot pick additional scopes that are outside of the App's allowed scopes
client_idID of your application; It can be found in the developer settings page.
redirect_uriThe URL where the user should return after granting access. You need to make sure you have added the uri into the redirect uris list of your application.
statestate parameter allows you to restore the previous state of your application after the user is redirected back. It is helpful to protect against Cross-Site Request Forgery. More details can be found here

A example request looks like

https://app.ramp.com/v1/authorize?response_type=code&scope=business:read transactions:read&client_id=ramp_id_i8ytO4Ad7W83VRupR1CpP7sPx4hlGQT479uj0xJof&redirect_uri=https://awesomeapp.io/callback.i

step 2: user is authenticated and prompted to grant data access

After the user is authenticated, he/she will the see the following pop-up.

step 3: user is redirected back with authorization_code

If the user choose to grant the access and click the Allow button, he/she will be redirected back to the redirect_uri with an authorization_code and a state

  • Retrieve the returned state param from the redirect and compare it with the one you stored earlier. If it doesn't match, you may be the target of an attack because this is either a response for an unsolicited request or someone trying to forge the response.
  • Retrieve the authorization_code and it will be used to exchange for an access_token in the next step

step 4: request for an access_token

With the authorization_code obtained from the previous step, you now can exchange it for an access_token; This need to be done by making a POST request to the token endpoint https://api.ramp.com/developer/v1/token

POST /v1/oauth/token HTTP/1.1
Authorization: Basic <base64-encoded client_id:client_secret>
Content-Type: application/json

{"grant_type":"authorization_code","code":"Pf2urddsDkDh3y8OnNpbFzOWRvY669wwO3J5SajfRl1FkZ50", "redirect_uri":"https://awesomeapp.io/callback"}

The request body need to contain the following fields

grant_typeMust be set to authorization_code
codeThe authorization code obtained from the previous step.
redirect_uriThe redirect URI previously used in the authorization request, for validation purposes

You'll also need to provide an Authorization header containing a base-64 representation of the client credentials.

Authorization: Basic <base64-encoded client_id:client_secret>

step 5: get an access_token

If the token request goes through, Ramp will return a response containing the access_token

    "scope":"business:read transactions:read"


Secure the tokens

The access tokens and refresh tokens should never be transmitted or store without encryption. You should consider using a strong encryption algorithm (e.g. AES).

step 6: get a new access_token using refresh_token

access_token has a limited lifespan and you could get a new access_token using the refresh_token without having to ask the user to re-grant the data access.

Note that you need to make sure the Refresh Token has been added in to the list of Grant types of your application. You can do that in the developer settings page.

To refresh the token, make a POST request to the token endpoint https://api.ramp.com/developer/v1/token with following required fields in the request body

grant_typeMust be set to refresh_token
refresh_tokenThe refresh token obtained from the previous token request

Client Credentials Grant

Client Credentials grant can be used to get an access token outside of the context of a user. It is typically used by application to access to its own resources directly, not on behalf of a user.

curl --location --request POST 'https://api.ramp.com/developer/v1/token' \
    --header 'Authorization: <base64-encoded client_id:client_secret>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=business:read transactions:read' 

The response will be a JSON payload containing a ready-to-use access_token. Note that this Client Credentials Grant does not produce refresh tokens, therefore you manually obtain new access tokens before the existing ones expire.