Authentication

The Loamly API uses API keys for authentication. All requests must include a valid API key in the Authorization header.

API keys

API keys are scoped to your workspace and provide full access to that workspace's data. Each workspace can have multiple API keys, allowing you to:

• Use different keys for different environments (dev, staging, prod)
• Use different keys for different services or integrations
• Rotate keys without downtime
• Revoke compromised keys immediately

Create an API key

1. Go to your Loamly dashboard → Settings → API Keys
2. Click Create API Key
3. Enter a name for the key (e.g., "Production API" or "Zapier Integration")
4. Click Create
5. Copy the key immediately — it will not be shown again

Using API keys

Include your API key in the Authorization header with the Bearer scheme:

curl -X GET "https://api.loamly.ai/v1/visitors" \
  -H "Authorization: Bearer loam_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Key format

Loamly API keys follow this format:

Example: JavaScript/TypeScript

const response = await fetch('https://api.loamly.ai/v1/visitors', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.LOAMLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Example: Python

import requests
import os

response = requests.get(
    'https://api.loamly.ai/v1/visitors',
    headers={
        'Authorization': f'Bearer {os.environ["LOAMLY_API_KEY"]}',
        'Content-Type': 'application/json',
    }
)

data = response.json()

Security best practices

• Never commit API keys to version control. Use environment variables or secrets management.
• Use different keys for different environments. This limits blast radius if a key is compromised.
• Rotate keys regularly. Create a new key, update your integrations, then delete the old key.
• Monitor key usage. Check the API Keys page for last used timestamps.
• Revoke unused keys. Delete any keys that are no longer in use.

Rate limits

API requests are rate-limited to ensure fair usage and platform stability:

Rate limit headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1703001234

Handling rate limits

If you exceed the rate limit, the API returns a 429 status code. Implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 1;
      await new Promise(r => setTimeout(r, retryAfter * 1000 * (i + 1)));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}