Skip to main content

​
Authentication

All programmatic API access to Bridgfy requires authentication using API keys. This page explains how to authenticate your requests and manage your API keys.

​
API Key Authentication

API keys are the primary method for programmatic access to the Bridgfy API. They are scoped to your Organization and can be created and managed through the Dashboard.

​
Using API Keys

Include your API key in the x-api-key header of every request: 
POST /api/deposit-intents
Host: api.bridgfy.com
x-api-key: bfy_your_api_key_here
Content-Type: application/json

{
  "userId": "user-123",
  "targetChainId": 137,
  "targetTokenAddress": "0x...",
  "targetAddress": "0x..."
}

​
Example with cURL

curl https://api.bridgfy.com/api/deposit-intents \
  -H "x-api-key: bfy_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "targetChainId": 137,
    "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "targetAddress": "0x5555555555555555555555555555555555555555"
  }'

​
Example with JavaScript

const response = await fetch('https://api.bridgfy.com/api/deposit-intents', {
  method: 'POST',
  headers: {
    'x-api-key': 'bfy_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user-123',
    targetChainId: 137,
    targetTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
    targetAddress: '0x5555555555555555555555555555555555555555'
  })
});

const data = await response.json();

​
Example with Python

import requests

headers = {
    'x-api-key': 'bfy_your_api_key_here',
    'Content-Type': 'application/json'
}

payload = {
    'userId': 'user-123',
    'targetChainId': 137,
    'targetTokenAddress': '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
    'targetAddress': '0x5555555555555555555555555555555555555555'
}

response = requests.post(
    'https://api.bridgfy.com/api/deposit-intents',
    headers=headers,
    json=payload
)

data = response.json()

​
Creating API Keys

API keys are created through the Bridgfy Dashboard:
  1. Sign in to https://dashboard.bridgfy.com
  2. Select your Organization from the organization switcher
  3. Navigate to “API Keys” section
  4. Click “Create API Key”
  5. Configure your key settings:
    • Label: Descriptive name for the key
    • Protocol Fee: Fee percentage in basis points (e.g., 50 = 0.5%)
    • Gas Sponsorship: Whether Bridgfy covers gas costs
  6. Copy the generated API key immediately (it won’t be shown again)
Important: Store your API keys securely. Treat them like passwords - never commit them to version control or share them publicly.

​
API Key Scope

API keys are scoped to your Organization, which means:
  • All executions created with a key are tracked to that Organization
  • Usage metrics and billing are aggregated per Organization
  • Team members in the Organization can view (but not access) key metadata
  • Keys can be revoked from the Dashboard at any time

​
Fee Configuration

Each API key has its own fee configuration: Protocol Fee (protocolFeeBps):
  • Set in basis points (1 bps = 0.01%)
  • Range: 0-1000 (0% to 10%)
  • Example: 50 bps = 0.5% fee
  • Deducted from deposits before bridging
  • Snapshotted onto Deposit Intents at creation
Gas Sponsorship (sponsoredGas):
  • true: Bridgfy pays all gas costs (better UX)
  • false: Gas deducted from user deposit (cost control)
  • Snapshotted onto Deposit Intents at creation
These settings allow you to create different API keys for different use cases (e.g., production vs. testing, different customer tiers).

​
Security Best Practices

​
Storage

DO:
  • Store API keys in environment variables
  • Use secrets management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Rotate keys periodically
  • Use different keys for development, staging, and production
DON’T:
  • Hardcode API keys in source code
  • Commit keys to version control
  • Share keys via email or messaging apps
  • Use production keys in client-side code

​
Key Management

Rotation:
  1. Create a new API key in the Dashboard
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. Revoke the old key
If Compromised:
  1. Immediately revoke the compromised key in the Dashboard
  2. Create a new API key
  3. Update your application
  4. Review recent execution logs for suspicious activity

​
Rate Limiting

API keys may be subject to rate limits based on your Organization’s plan:
  • Requests per second: Limits vary by endpoint
  • Monthly executions: May be limited based on your plan
  • Quota exceeded: Results in QUOTA_EXCEEDED status
If you need higher limits, upgrade your Organization’s plan in the Dashboard.

​
Error Responses

​
Invalid API Key

Status: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
Causes:
  • API key doesn’t exist
  • API key has been revoked
  • API key is malformed
Solution: Verify you’re using the correct API key and that it hasn’t been revoked.

​
Missing API Key

Status: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Missing API key",
  "error": "Unauthorized"
}
Causes:
  • x-api-key header not included in request
Solution: Add the x-api-key header to your request.

​
Insufficient Permissions

Status: 403 Forbidden 
{
  "statusCode": 403,
  "message": "Insufficient permissions",
  "error": "Forbidden"
}
Causes:
  • API key role doesn’t have required permissions for the endpoint
Solution: Verify your API key has the CLIENT role. Only CLIENT keys can access integration endpoints.

​
Quota Exceeded

Status: 429 Too Many Requests 
{
  "statusCode": 429,
  "message": "Quota exceeded",
  "error": "Too Many Requests"
}
Causes:
  • Organization has exceeded monthly execution limit
  • Rate limit exceeded
Solution: Upgrade your Organization’s plan or wait for quota reset.

​
Testing

​
Health Check Endpoint

Test API connectivity without authentication: 
GET /api/health
Host: api.bridgfy.com
Response: 
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
This endpoint requires no authentication and can be used to verify the API is accessible.

​
Next Steps