Skip to main content
RebelFi uses API key authentication for all programmatic API access and agent integration.
Dashboard Users: The RebelFi dashboard uses internal JWT authentication for user sessions. This guide covers only API key authentication for API integration, which is what you’ll need for programmatic access and custom agents.

​
API Key Authentication

​
Generating API Keys

  • Dashboard
  • API
  1. Navigate to Settings → API Keys
  2. Click Generate API Key
  3. Provide a descriptive name (e.g., “Production Agent”, “Dev Environment”)
  4. Copy and securely store the key (shown only once)

​
API Key Format

RebelFi API keys follow this format: 
rfk_{environment}_{random_string}
Examples:
  • rfk_test_xxxxxxxxxxx - Test/development key
  • rfk_live_xxxxxxxxxxx - Production key

​
Using API Keys

Include the API key in the X-API-Key header: 
const response = await fetch('https://api.rebelfi.io/api/agent/transactions/poll', {
  method: 'POST',
  headers: {
    'X-API-Key': 'rfk_live_xxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    leaseDurationMs: 30000
  })
});

# Using cURL
curl https://api.rebelfi.io/api/agent/transactions/poll \
  -X POST \
  -H "X-API-Key: rfk_live_xxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"leaseDurationMs": 30000}'

​
API Key Access

API keys provide full access to your organization’s resources, including:
  • Agent polling endpoints (/api/agent/*)
  • Wallet management (/api/core/wallets/*)
  • Operation management (/api/core/operations/*)
  • Allocation management (/api/v1/allocations/*)
API keys have full organization-level access. Store them securely and rotate them regularly. Create separate keys for different environments (dev, staging, production).

​
Security Best Practices

​
API Key Management

DO:
  • Store in environment variables
  • Use secrets management (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)
  • Encrypt at rest
DON’T:
  • Commit to version control
  • Store in code or configuration files
  • Share via email or chat
  • Log in plain text
Rotate API keys regularly:
  1. Generate new API key
  2. Deploy new key to production (blue/green deployment)
  3. Verify new key works
  4. Revoke old key
  5. Update documentation
Recommended frequency: Every 90 days
Use different API keys for each environment:
  • Development: rfk_test_dev_xxx
  • Staging: rfk_test_staging_xxx
  • Production: rfk_live_prod_xxx
This limits blast radius if a key is compromised.
Grant minimum required scopes:
// Agent only needs agent scope
{
  name: 'Production Agent',
  scopes: ['agent']
}

// Dashboard integration needs more
{
  name: 'Dashboard Backend',
  scopes: ['wallets', 'operations', 'allocations']
}

​
Rate Limiting

RebelFi enforces rate limits for API key authentication:
  • Agent Polling: 1000 requests/minute
  • Transaction Reporting: 500 requests/minute
  • Standard APIs: 100 requests/minute

​
Handling Rate Limits

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      // Rate limited
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Retrying after ${retryAfter}s`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

​
Testing Authentication

​
Validate API Key

curl https://api.rebelfi.io/api/core/apikeys/validate \
  -X POST \
  -H "X-API-Key: rfk_test_xxxxxxxxxxxxx"

const response = await fetch('https://api.rebelfi.io/api/core/apikeys/validate', {
  method: 'POST',
  headers: { 'X-API-Key': 'rfk_test_xxxxxxxxxxxxx' }
});

const { data } = await response.json();
console.log('Valid:', data.valid);

​
Test JWT Token

// Get current user with token
const response = await fetch('https://api.rebelfi.io/api/core/user', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

if (response.ok) {
  console.log('Token is valid');
} else if (response.status === 401) {
  console.log('Token is invalid or expired');
}

​
Troubleshooting

Cause: Invalid or expired credentialsSolution:
  • Verify API key or JWT token is correct
  • Check token hasn’t expired
  • Ensure proper header format (Authorization: Bearer ... or X-API-Key: ...)
  • Try generating a new API key
Cause: Valid credentials but insufficient permissionsSolution:
  • Check API key scopes include required permissions
  • Verify user has access to the organization
  • Check resource ownership (e.g., accessing another org’s wallets)
Cause: Too many requests in time windowSolution:
  • Implement exponential backoff
  • Reduce request frequency
  • Use webhooks instead of polling (where available)
  • Contact support for higher limits if needed

​
Next Steps

Custody Integration

Set up your custody agent with authentication

API Reference

Explore authenticated API endpoints