OAuth 2.0

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

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

<redirect_uri>?code=<authorization_code>&state=<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

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

{
    "access_token":"ramp_tok_o4bfbrfhDBdXcjjTBMD1iTTXdprRuHdcmne8gR5zfSV78uPe",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"ramp_tok_IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
    "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

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.