API Keys

Manage your API credentials for submitting leads to Ledly.

Overview

API keys authenticate your lead submissions. Each key is associated with your vendor account and includes:

• Key ID - Public identifier
• API Key - Secret authentication token
• Permissions - What the key can access
• Rate Limits - Request limits per minute

Generating an API Key

Using Your API Key

Include the API key in the Authorization header:

curl -X POST https://api.ledly.io/api/leads/inbound \
  -H "Authorization: Bearer vk_live_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Key Formats

Managing Keys

Viewing Keys

Your active keys show:

• Key name
• Created date
• Last used
• Status (active/revoked)

Revoking a Key

If a key is compromised:

1. Go to Settings → API Keys
2. Find the compromised key
3. Click Revoke
4. Confirm revocation

Regenerating a Key

To get a new key without revoking:

1. Click Regenerate next to the key
2. The old key remains active for 24 hours
3. Update your systems with the new key
4. Old key automatically expires

Multiple Keys

You can have multiple API keys for different purposes:

Best Practices

• Separate production and development - Never use production keys for testing
• Name keys descriptively - Know which system uses which key
• Rotate regularly - Replace keys every 6-12 months
• Revoke unused keys - Remove keys for decommissioned systems

Rate Limits

Each API key has rate limits:

Rate Limit Headers

Response headers show your limit status:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 1703505600

When Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded",
  "retry_after": 30
}

Solution: Wait retry_after seconds or implement backoff.

IP Whitelisting

Optionally restrict key usage to specific IPs:

1. Go to Settings → API Keys
2. Select a key → IP Whitelist
3. Add allowed IP addresses/ranges
4. Save

Whitelist Formats

Single IP:      203.0.113.50
Range (CIDR):   203.0.113.0/24
Multiple:       203.0.113.50, 203.0.113.51

Key Usage Statistics

Monitor your API key usage:

Available Metrics

Viewing Stats

1. Go to Settings → API Keys
2. Click Stats next to any key
3. View usage over time

Security Best Practices

Do:

• Store keys in environment variables
• Use secrets management (Vault, AWS Secrets Manager)
• Rotate keys regularly
• Use separate keys per environment
• Monitor for unusual activity

Don’t:

• Commit keys to version control
• Share keys via email or chat
• Use production keys for development
• Log keys in plain text
• Hardcode keys in source code

Secure Storage Examples

Environment Variable:

export LEDLY_API_KEY="vk_live_abc123xyz..."

Node.js (.env file):

LEDLY_API_KEY=vk_live_abc123xyz...

Python:

import os
api_key = os.environ.get('LEDLY_API_KEY')

Troubleshooting

”Invalid API Key” Error

• Verify the key was copied correctly (no extra spaces)
• Check the key hasn’t been revoked
• Ensure you’re using the correct environment (prod vs sandbox)
• Confirm the key prefix matches the endpoint

”Forbidden” (403) Error

• Check if IP whitelisting is enabled
• Verify your IP is in the whitelist
• Confirm the key has required permissions

”Rate Limited” (429) Error

• Implement exponential backoff
• Check X-RateLimit-Remaining before requests
• Request a rate limit increase if needed

API Key Lifecycle

Generate → Active → (Optional: Regenerate) → Revoke → Deleted