This page explains how to authenticate with the Ravelin API.
On this page:Ravelin uses API keys and token authentication to allow access to our API. These keys may be permanent with no expiration or short-lived keys generated using OAuth 2.0.
Your permanent API keys can be found under the API Keys tab in the Developer section of the dashboard.
OAuth-generated keys are not visible in the dashboard.
All API requests should also be made using HTTPS.
Your Secret API Keys should be used when sending requests to api.ravelin.com and will either have the prefix sk_ or secret_key_.
You should include your Secret API Key in the Authorization header of all requests to api.ravelin.com in the format:
Authorization: token sk_live_your_secret_key.
For example:
$ curl "https://api.ravelin.com/v2/checkout" \
-H "Authorization: token sk_live_your_secret_key" \
-X POST
...
Publishable Keys are safe to publish on your website front-end and safe to appear in your logs. In this respect they are conceptually comparable to public keys in asymmetric cryptography.
Ravelin’s Publishable Keys have a highly constrained role and scope and will be accepted only by specific API endpoints, for example to create session-tracking events.
The use of Ravelin’s client-side card encryption alongside publishable keys allows merchants to minimise their PCI exposure by ensuring card details are fully encrypted before being passed out of the client-side browser or app environment scope into their backend environment scope.
Your Publishable API Keys (and, if provided, your Public RSA Keys) should be used by the ravelinjs JavaScript SDK, the iOS SDK, or the Android SDK.
To aid with identification, Publishable API Keys will always have the prefix pk_ or publishable_key_.
Publishable keys cannot be generated using OAuth and have no expiration.
You can request new secret API keys by contacting Ravelin support or by using OAuth 2.0.
Ravelin supports the OAuth 2.0 client credentials flow for server-to-server (machine-to-machine) authentication. Your backend exchanges a long-lived client credential pair for a short-lived secret API key which is used as described in Secret API Keys.
To enable OAuth 2.0 for your account, contact Ravelin support.
Client credentials (a Client ID and Client Secret pair) are managed in the Developer section of the Ravelin Dashboard.
You may perform the following operations on credentials:
⚠️ IMPORTANT: Copy the secret immediately upon creation as it is only shown once and cannot be retrieved later.
To request a new short-lived OAuth token you should send a POST request to https://api.ravelin.com/oauth/token with Content-Type: application/x-www-form-urlencoded and grant_type=client_credentials in the form data.
Do not include a scope parameter as this is reserved for future use. Credentials may be supplied in the request body or via HTTP Basic Authentication.
Request body:
curl "https://api.ravelin.com/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
Basic Authentication:
curl "https://api.ravelin.com/oauth/token" \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"
The response contains the access token and its lifetime in seconds:
{
"access_token": "secret_key_...",
"token_type": "Bearer",
"expires_in": 86400
}
Tokens expire after 24 hours. You should therefore cache the token and reuse it for its full lifetime. Requesting a new token on every API call will cause high latency and may trigger rate limiting.
You should refresh the token proactively around 10 minutes before expiry to avoid request failures during renewal.
OAuth 2.0 client libraries will typically handle token caching and refresh automatically.
You have both live and sandbox API keys.
Keys for use with your sandbox account include the term _test_,
while keys for use with your live account include the term _live_.
Your permanent sandbox keys can be accessed in the same API Keys tab in the Developer section of the dashboard, when you’ve switched to your sandbox account from the account menu.
Sandbox keys may be created using OAuth by creating credentials in the Developer section of the dashboard.
Was this page helpful?