Skip to main content

​
Authentication

NowRamp uses API keys for authentication. This guide covers how to obtain, use, and manage your API keys.

​
Getting Your API Key

​
Via Partner Dashboard

  1. Log in to your Partner Dashboard
  2. Navigate to Settings > API Keys
  3. Click Create New Key
  4. Copy and securely store the key
API keys are only shown once when created. Make sure to copy and store them securely before closing the dialog.

​
Using Your API Key

Include your API key in the X-API-Key header with every request: 
curl https://api.nowramp.com/v1/quotes \
  -H "X-API-Key: ramp_live_abc123xyz789"

​
JavaScript Example

const apiKey = process.env.RAMP_API_KEY;

async function fetchQuotes() {
  const response = await fetch('https://api.nowramp.com/v1/quotes', {
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json',
    },
  });
  return response.json();
}

​
Python Example

import requests
import os

api_key = os.environ.get('RAMP_API_KEY')

response = requests.get(
    'https://api.nowramp.com/v1/quotes',
    headers={'X-API-Key': api_key}
)

​
Key Types

TypePrefixUsage
Liveramp_live_Production API calls
Testramp_test_Sandbox/testing
Never use test keys in production or expose live keys in client-side code.

​
Scoped Permissions

API keys can be scoped to specific permissions: 
{
  "permissions": [
    "quotes:read",
    "quotes:write",
    "orders:read",
    "orders:write"
  ]
}
Available scopes:
  • quotes:read/write
  • orders:read/write
  • customers:read/write
  • wallets:read/write
  • kyc:read/write
  • webhooks:read/write

​
Security Best Practices

​
1. Environment Variables

Store keys in environment variables, never in code: 
# .env (never commit this file)
RAMP_API_KEY=ramp_live_abc123xyz789

// Load from environment
const apiKey = process.env.RAMP_API_KEY;

​
2. Server-Side Only

API keys should only be used server-side. For client-side integrations, use the widget which handles authentication automatically. 
// WRONG - Client-side exposure
<script>
  const API_KEY = "ramp_live_abc123"; // Never do this!
</script>

// CORRECT - Server-side proxy
app.post('/api/create-quote', async (req, res) => {
  const response = await fetch('https://api.nowramp.com/v1/quotes', {
    headers: { 'X-API-Key': process.env.RAMP_API_KEY },
    body: JSON.stringify(req.body),
  });
  res.json(await response.json());
});

​
3. Key Rotation

Rotate your API keys regularly. You can rotate keys in the Partner Dashboard:
  1. Go to Settings > API Keys
  2. Click the Rotate button next to the key you want to rotate
  3. Confirm the rotation and copy the new key
  4. Update your application with the new key before the grace period expires
When you rotate a key, the old key remains valid for a 24-hour grace period to allow for seamless transitions.

​
4. IP Allowlisting

Contact support to enable IP allowlisting for additional security.

​
5. Audit Logs

Monitor API key usage in the dashboard under Settings > Audit Logs.

​
Handling Authentication Errors

Error CodeDescriptionSolution
MISSING_API_KEYNo key in headerAdd X-API-Key header
INVALID_API_KEYKey is invalidCheck key value
API_KEY_EXPIREDKey has expiredCreate a new key
INSUFFICIENT_PERMISSIONSMissing scopeAdd required permission
async function apiCall(endpoint, options) {
  const response = await fetch(endpoint, {
    ...options,
    headers: {
      'X-API-Key': apiKey,
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!data.success && data.error.code === 'INVALID_API_KEY') {
    // Handle invalid key - maybe refresh from secrets manager
    throw new Error('API key is invalid. Please check configuration.');
  }

  return data;
}

​
Widget Authentication

The embeddable widget uses a different authentication flow:
  1. Widget is initialized with your API key and project ID
  2. Widget creates a secure session for the customer
  3. All subsequent calls use the session token
import { RampWidget } from '@ramp-orchestrator/sdk';

const widget = new RampWidget({
  apiKey: 'ramp_live_abc123',  // This is safe - widget handles securely
  projectId: 'project_xyz789',
  externalUserId: 'user_123',
});
The widget’s architecture ensures your API key is never exposed to end users.