Building a Dench App That Calls External APIs

Learn how to build a DenchClaw app that calls external APIs using dench.http.fetch(), handle authentication, manage rate limits, and store API keys securely.

Mark Rachapoom

March 26, 2026·5 min read

DenchClaw runs locally, which means your apps are subject to the same browser restrictions as any web app: CORS blocks most external API calls. The dench.http.fetch() bridge API solves this — it proxies requests through the DenchClaw backend, which runs server-side without CORS restrictions.

This guide covers everything about building apps that call external APIs: the http:external permission, authentication patterns, rate limiting, error handling, and secure key storage.

The `dench.http.fetch()` API#

The interface mirrors the standard fetch() API but runs server-side:

const response = await dench.http.fetch(url, options);

Parameters:

url — The target URL (must be HTTPS for external calls)
options.method — HTTP method (GET, POST, PUT, DELETE)
options.headers — Request headers object
options.body — Request body (string or JSON-serializable object)
options.timeout — Request timeout in milliseconds (default: 30000)

Returns: A response object with status, headers, and json() / text() methods.

Required permission: http:external in .dench.yaml.

Pattern 1: Simple GET Request#

// Weather API example (no authentication required)
const weather = await dench.http.fetch(
  'https://wttr.in/San+Francisco?format=j1',
  { method: 'GET' }
);
const data = await weather.json();
console.log(data.current_condition[0].temp_C);

Pattern 2: Authenticated API (Bearer Token)#

Most production APIs require authentication. Store the token in dench.store rather than hardcoding it:

async function fetchWithAuth(url, options = {}) {
  const apiKey = await dench.store.get('my_api_key');
  if (!apiKey) {
    throw new Error('API key not configured. Set it in app settings.');
  }
  
  return dench.http.fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
}
 
// Usage
const response = await fetchWithAuth('https://api.example.com/v1/companies');
const data = await response.json();

Pattern 3: API Key in Settings UI#

Build a settings panel so users can enter their API keys:

async function checkApiKey() {
  const key = await dench.store.get('apollo_api_key');
  if (!key) {
    document.getElementById('app').innerHTML = `
      <div class="settings-prompt">
        <h2>Configure API Key</h2>
        <p>This app requires an Apollo.io API key.</p>
        <input type="password" id="apiKeyInput" placeholder="Enter your API key...">
        <button onclick="saveApiKey()">Save</button>
        <a href="https://app.apollo.io/#/settings/integrations/api" target="_blank">Get API key →</a>
      </div>
    `;
    return false;
  }
  return true;
}
 
async function saveApiKey() {
  const key = document.getElementById('apiKeyInput').value;
  if (!key) return;
  await dench.store.set('apollo_api_key', key);
  await dench.ui.toast({ message: 'API key saved', type: 'success' });
  location.reload();
}

Pattern 4: Rate Limiting#

Most APIs have rate limits. Implement a simple rate limiter:

class RateLimiter {
  constructor(requestsPerSecond) {
    this.interval = 1000 / requestsPerSecond;
    this.lastCall = 0;
  }
  
  async wait() {
    const now = Date.now();
    const timeSinceLast = now - this.lastCall;
    if (timeSinceLast < this.interval) {
      await new Promise(r => setTimeout(r, this.interval - timeSinceLast));
    }
    this.lastCall = Date.now();
  }
}
 
const limiter = new RateLimiter(2); // 2 requests per second
 
async function enrichBatch(contacts) {
  const results = [];
  for (const contact of contacts) {
    await limiter.wait();
    const result = await enrichContact(contact);
    results.push(result);
  }
  return results;
}

Pattern 5: Retry on Failure with Exponential Backoff#

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  let lastError;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await dench.http.fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited — wait and retry
        const retryAfter = Number(response.headers['retry-after'] || (2 ** attempt));
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
      }
      
      return response;
    } catch (err) {
      lastError = err;
      if (attempt < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 2 ** attempt * 1000)); // Exponential backoff
      }
    }
  }
  throw lastError;
}

Real-World Example: Apollo.io Lead Enrichment#

Here's a complete example integrating with Apollo.io's People API:

async function enrichWithApollo(contact) {
  const apiKey = await dench.store.get('apollo_api_key');
  
  const response = await dench.http.fetch(
    'https://api.apollo.io/api/v1/people/match',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Cache-Control': 'no-cache'
      },
      body: JSON.stringify({
        api_key: apiKey,
        first_name: contact['Full Name']?.split(' ')[0],
        last_name: contact['Full Name']?.split(' ').slice(1).join(' '),
        organization_name: contact.Company,
        email: contact['Email Address']
      })
    }
  );
  
  if (!response.ok) {
    throw new Error(`Apollo API error: ${response.status}`);
  }
  
  const data = await response.json();
  const person = data.person;
  
  if (!person) return null;
  
  return {
    linkedin_url: person.linkedin_url,
    title: person.title,
    company_size: person.organization?.estimated_num_employees,
    company_domain: person.organization?.primary_domain,
    phone: person.phone_numbers?.[0]?.raw_number
  };
}

Handling Common Error Cases#

async function safeExternalCall(url, options) {
  try {
    const response = await dench.http.fetch(url, { ...options, timeout: 10000 });
    
    switch (response.status) {
      case 200:
      case 201:
        return await response.json();
      case 401:
        await dench.store.delete('api_key'); // Clear invalid key
        throw new Error('Invalid API key. Please reconfigure.');
      case 403:
        throw new Error('Access denied. Check your API plan limits.');
      case 404:
        return null; // Not found is not an error
      case 429:
        throw new Error('Rate limit exceeded. Wait before retrying.');
      case 500:
      case 502:
      case 503:
        throw new Error('API service temporarily unavailable.');
      default:
        throw new Error(`Unexpected status: ${response.status}`);
    }
  } catch (err) {
    if (err.name === 'TimeoutError') {
      throw new Error('Request timed out. The API may be slow.');
    }
    throw err;
  }
}