Cardholders may find other articles in the Ramp overview section to be more applicable.
Overview
Ramp provides an API to programmatically access data and take action. The Ramp API uses an OAuth 2.0 flow to generate credentials to auth against the Ramp API. The OAuth 2.0 flow generates a client ID, client secret, access token(s), and refresh token(s). You can find documentation for the OAuth 2.0 flow for the Ramp API here.
This article describes the steps to take if any of these credentials are leaked.
Client ID
A client ID is a public identifier for your app. Because a client ID is public, a leaked client ID is not a critical security concern and no action needs to be taken. However, it’s good practice to understand how the client ID was leaked (e.g., hard coded in a code repository) and fix the source of the leak to maintain good configuration management hygiene.
Client secret
A client secret is a private key that’s generated for your app to authenticate against the API in conjunction with the client ID. Because the client secret is a private credential that’s used to authenticate your app, if a client secret is leaked it should be rotated in the app settings page.
Follow these steps to rotate a client secret. Note, you will need to be an Admin to see these options.
- Go to app.ramp.com. On the left-hand sidebar, click on “Settings” > “Ramp developer”.
- On the right side of the screen, click the name of the app whose secret leaked to open the configuration menu.
- At the top of the drawer, click Show Client Secret to load additional configuration options. You will be prompted to enter a code from your Authenticator device.
Rotating the client secret prevents authentication to the API using previously generated credentials. Specifically it:
- Prevents new authorization code grants
- Prevents new refresh token grants
- Prevents new client credentials crants
- Invalidates current access tokens
- Invalidates current refresh tokens
Therefore, once you update the client secret, your app will need a prompt update to use the new client secret. Users will need to re-authenticate with your app as well.
Access token
An access token is used to authenticate requests to the Ramp API. Access tokens generated using the authorization code grant and refresh token grant expire after one hour, whereas access tokens generated using the client credentials grant expire after 10 days. Since some access tokens take 10 days to expire, we recommend revoking a leaked access token unless you know it’s an access token with a limited one hour expiry. It’s also important to promptly investigate the source of the leak to prevent future leaks of an access token.
If desired, you can revoke an individual access token using the Ramp API.
You should consider invalidating all access tokens if there’s a risk that additional access tokens will continue to be leaked and exploited. Rotate the client secret to invalidate all existing access tokens for the app (see above).
Refresh token
A refresh token, in combination with a client ID and client secret, is used to generate new access tokens (the Refresh Token Grant). Refresh tokens do not expire. The impact of leaked refresh tokens is mitigated because a leaked refresh token alone cannot be used to generate new access tokens. However, it’s still important to quickly ascertain the source of the leak to prevent future leaks and you should strongly consider revoking the leaked refresh token.
If desired, you can revoke an individual refresh token using the Ramp API. Moreover, if deemed necessary, you can invalidate all refresh tokens for an app by rotating the client secret (see above).