API Key Management

Complete guide to managing your API keys for test and production environments.

Overview

RACH supports three types of API keys for maximum flexibility and backwards compatibility:

Key Type	Prefix	Environment	Use Case
Test	test_sk_	Testnet	Development, testing, sandbox
Production	live_sk_	Mainnet	Live transactions, real money
Legacy	No prefix	Mainnet	Backwards compatibility

How It Works

The API automatically detects which environment to use based on your API key prefix only:

test_sk_... → Testnet (BSC Testnet, ETH Sepolia, etc.)
live_sk_... → Mainnet (BSC, Ethereum, Polygon, etc.)
abc123...   → Mainnet (legacy keys default to production)

No flags or parameters needed! The system determines everything from the key.

---

Getting Your API Keys

For New Users

API keys are automatically generated when you register:

POST /api/v1/auth/register

You receive:

• ✅ Legacy key (backwards compatibility)
• ✅ Test key (test_sk_...)
• ✅ Production key (live_sk_...)

For Existing Users

If you registered before the 3-key system, initialize your keys:

Endpoint: POST /api/v1/api-keys/initialize

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/api-keys/initialize \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "message": "API keys initialized successfully",
  "test_key": "test_sk_abc123...",
  "production_key": "live_sk_xyz789...",
  "instructions": {
    "test": "Use test_sk_ prefix for testnet/sandbox",
    "production": "Use live_sk_ prefix for mainnet",
    "legacy": "Old keys still work"
  }
}

---

Retrieve Your Keys

Endpoint: GET /api/v1/api-keys

curl https://api.rach.finance/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "test_key": "test_sk_abc123def456...",
  "production_key": "live_sk_xyz789ghi012...",
  "test_mode": true,
  "sandbox_balance": "10000.00"
}

---

Using API Keys

In Your Requests

Add the X-API-Key header to all API calls:

curl -X POST https://api.rach.finance/api/v1/checkout/create \
  -H "X-API-Key: test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}'

Test Environment Example

const testKey = 'test_sk_abc123...';

const response = await fetch('https://api.rach.finance/api/v1/checkout/create', {
  method: 'POST',
  headers: {
    'X-API-Key': testKey,  // ← Uses testnet automatically
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'USDT',
    network: 'BSC',  // BSC Testnet used
    // ... other fields
  })
});

Production Environment Example

const prodKey = 'live_sk_xyz789...';

const response = await fetch('https://api.rach.finance/api/v1/checkout/create', {
  method: 'POST',
  headers: {
    'X-API-Key': prodKey,  // ← Uses mainnet automatically
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'USDT',
    network: 'BSC',  // BSC Mainnet used
    // ... other fields
  })
});

---

Rotate API Keys

Rotate keys for security or if compromised.

Rotate Test Key

Endpoint: POST /api/v1/api-keys/rotate/test

curl -X POST https://api.rach.finance/api/v1/api-keys/rotate/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "test_key": "test_sk_NEW_KEY_HERE...",
  "message": "Test API key rotated successfully"
}

Rotate Production Key

Endpoint: POST /api/v1/api-keys/rotate/production

curl -X POST https://api.rach.finance/api/v1/api-keys/rotate/production \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Warning

Old key becomes invalid immediately! Update your integrations before rotating production keys.

---

Sandbox Mode

Test mode includes a sandbox balance for testing without real funds.

Check Sandbox Balance

Endpoint: GET /api/v1/api-keys/sandbox/balance

curl https://api.rach.finance/api/v1/api-keys/sandbox/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Reset Sandbox Balance

Endpoint: POST /api/v1/api-keys/sandbox/reset

Resets your sandbox balance to $10,000 USDT for testing.

---

Security Best Practices

1. Never Expose API Keys

Critical

• ❌ Never commit to Git
• ❌ Never log API keys
• ❌ Never expose in client-side code
• ❌ Never share publicly

Do This

• ✅ Store in environment variables
• ✅ Use backend/server-side only
• ✅ Rotate keys regularly
• ✅ Use test keys during development

2. Environment Variables

# .env file
RACH_TEST_API_KEY=test_sk_your_test_key
RACH_PROD_API_KEY=live_sk_your_prod_key

// In your code
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.RACH_PROD_API_KEY
  : process.env.RACH_TEST_API_KEY;

3. Key Rotation Schedule

• Production Keys: Rotate every 90 days
• Test Keys: Rotate after major testing cycles
• Compromised Keys: Rotate immediately

---

Test vs Production Comparison

Feature	Test Mode (test_sk_)	Production Mode (live_sk_)
Network	Testnet (BSC Testnet, Sepolia, etc.)	Mainnet (BSC, Ethereum, etc.)
Funds	Free test tokens from faucets	Real money
Transactions	Reversible, unlimited	Permanent, count against limits
Fees	No fees (or testnet fees)	Real blockchain fees
Webhooks	Sent to test URLs	Sent to prod URLs
KYC	Not required	Required for activation

---

Troubleshooting

Error: "Invalid API key"

Cause: Wrong key or key not initialized

Solution:

1. Check you're using the correct key
2. Verify key hasn't been rotated
3. For existing users, call /api-keys/initialize

Wrong Environment Used

Cause: Using wrong API key type

Solution:

• Check your key prefix:
  • test_sk_ → Testnet
  • live_sk_ → Mainnet
• Verify you're using the intended key

Legacy Key Not Working

Cause: Account might be deactivated

Solution:

1. Check KYC status
2. Contact support if account suspended
3. Migrate to new key system via /api-keys/initialize

---

Next Steps

• Authentication Guide
• Crypto Gateway Integration
• Wallet Service Integration
• Webhook Configuration