Skip to main content

Getting Your API Key

To send notifications, you’ll need to authenticate as an application using your API key. If you don’t have your key yet, please open a ticket in our discord channel.

Using Your API Key

Include your API key in the x-dialect-api-key header for all server-side requests:
const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/subscribers`, {
  method: 'GET',
  headers: {
    'x-dialect-api-key': 'YOUR_API_KEY'
  }
});

const { subscribers } = await response.json();

Error Handling

Common Authentication Errors

401 Unauthorized: Invalid or missing API key
{
  "error": "Unauthorized"
}
403 Forbidden: Valid API key but insufficient permissions
{
  "error": "Forbidden"
}

Error Handling Example

async function sendNotificationSafely(appId: string, apiKey: string, message: any) {
  try {
    const response = await fetch(`https://alerts-api.dial.to/v2/${appId}/send`, {
      method: 'POST',
      headers: {
        'x-dialect-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(message)
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 403:
          throw new Error('Access denied. Check your app permissions.');
        default:
          throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
      }
    }

    return response.json();
  } catch (error) {
    console.error('Failed to send notification:', error);
    throw error;
  }
}

Best Practices

💡 Security:
  • Store API keys securely (environment variables, secrets management)
  • Never expose API keys in client-side code
  • Use HTTPS for all API communication
💡 Error Handling:
  • Always check response status codes
  • Implement proper retry logic for transient failures
  • Log authentication errors for debugging
💡 Rate Limiting:
  • Respect API rate limits to avoid being blocked
  • Implement exponential backoff for retries