Skip to main content

🔐 Authentication

Sendly uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Key Types​

Sendly provides two types of API keys:

🧪 Test Keys​

  • Format: sl_test_xxxxxxxxxx
  • Purpose: Development and testing
  • Behavior: No SMS sent, no charges
  • Rate Limits: Same as live keys
  • Webhooks: Simulated events

🚀 Live Keys​

  • Format: sl_live_xxxxxxxxxx
  • Purpose: Production use
  • Behavior: Real SMS sent, charges apply
  • Rate Limits: Based on your plan
  • Webhooks: Real delivery events

Getting Your API Key​

  1. Sign up at sendly.live
  2. Navigate to your dashboard
  3. Go to API Keys section
  4. Create a new key or copy existing ones
  5. Choose test or live mode
🔒 Security Best Practices
  • Never expose API keys in client-side code
  • Use environment variables for API keys
  • Rotate keys regularly
  • Use test keys for development
  • Monitor key usage in dashboard

Authentication Methods​

The most common and secure method:

Using Authorization Header
curl -X POST https://sendly.live/api/v1/send \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "text": "Hello world!"
  }'

SDK Authentication​

All our SDKs handle authentication automatically:

Node.js SDK Authentication
import { SendlyClient } from '@sendly/node';

// Option 1: Direct API key
const sendly = new SendlyClient({
  apiKey: 'sl_live_YOUR_API_KEY'
});

// Option 2: Environment variable (recommended)
// Set SENDLY_API_KEY in your environment
const sendly = new SendlyClient(); // Auto-loads from env

// Option 3: Custom configuration
const sendly = new SendlyClient({
  apiKey: process.env.SENDLY_API_KEY,
  baseURL: 'https://sendly.live/api', // Optional
  timeout: 30000 // Optional timeout in ms
});

Environment Variables​

Setting Environment Variables​

~/.bashrc or ~/.zshrc
# Add to your shell configuration file
export SENDLY_API_KEY="sl_live_YOUR_API_KEY"

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Error Handling​

Authentication Errors​

When authentication fails, you'll receive a 401 Unauthorized response:

Authentication Error Response
{
  "error": "authentication_error",
  "message": "Invalid API key provided",
  "code": "invalid_api_key",
  "statusCode": 401
}

Common Authentication Issues​

IssueCauseSolution
401 UnauthorizedInvalid API keyCheck key format and validity
401 UnauthorizedMissing Authorization headerAdd Authorization: Bearer <key>
403 ForbiddenAPI key lacks permissionsUse correct key type (test/live)
429 Rate LimitedToo many requestsImplement rate limiting

SDK Error Handling​

Handle Authentication Errors
import { SendlyClient, SendlyError } from '@sendly/node';

const sendly = new SendlyClient({
  apiKey: 'sl_live_YOUR_API_KEY'
});

try {
  const result = await sendly.sms.send({
    to: '+1234567890',
    text: 'Hello world!'
  });
  console.log('Success:', result.messageId);
} catch (error) {
  if (error instanceof SendlyError) {
    switch (error.code) {
      case 'authentication_error':
        console.error('Invalid API key:', error.message);
        break;
      case 'rate_limit_exceeded':
        console.error('Rate limited:', error.message);
        break;
      default:
        console.error('API error:', error.message);
    }
  } else {
    console.error('Network error:', error.message);
  }
}

API Key Management​

Dashboard Features​

Access your API key management in the Sendly Dashboard:

  • 📊 Usage Analytics - Monitor API key usage and costs
  • 🔄 Key Rotation - Create new keys and deactivate old ones
  • ⚙️ Permissions - Set key-specific permissions and limits
  • 📈 Rate Limits - View and upgrade rate limits
  • 🔔 Alerts - Set up usage and security alerts

Key Rotation Best Practices​

  1. Regular Rotation - Rotate keys every 90 days
  2. Gradual Migration - Deploy new keys before deactivating old ones
  3. Monitoring - Watch for authentication errors during rotation
  4. Documentation - Update your team's documentation
Key Rotation Example
// Step 1: Create new API key in dashboard
// Step 2: Update your environment variables
const oldKey = process.env.SENDLY_API_KEY_OLD;
const newKey = process.env.SENDLY_API_KEY_NEW;

// Step 3: Gradual migration with fallback
const sendly = new SendlyClient({
  apiKey: newKey || oldKey
});

// Step 4: Monitor and remove old key

Security Considerations​

✅ Do's​

  • ✅ Use environment variables for API keys
  • ✅ Implement proper error handling
  • ✅ Monitor API key usage regularly
  • ✅ Use test keys for development
  • ✅ Rotate keys regularly
  • ✅ Set up rate limiting
  • ✅ Use HTTPS for all requests

❌ Don'ts​

  • ❌ Hardcode API keys in source code
  • ❌ Commit API keys to version control
  • ❌ Share API keys in public channels
  • ❌ Use live keys for testing
  • ❌ Ignore authentication errors
  • ❌ Use HTTP for API requests

Webhook Authentication​

Webhooks also require authentication to ensure security:

Webhook Signature Verification
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
    
  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-sendly-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.SENDLY_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});
🆘 Need Help?

Next Steps​

Now that you understand authentication, explore these guides: