Authentication

Authentication Methods

StartMessaging uses Bearer token authentication for all API requests. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API Key Management

Generating Keys

1. Navigate to Settings → API Keys in your dashboard
2. Click Generate New Key
3. Give it a descriptive label (e.g., “Production Server”, “Staging”)
4. Copy the key immediately — it won’t be shown again

Key Types

Key Type	Scope	Use Case
Production	Full access	Live messaging, webhooks, templates
Sandbox	Sandbox only	Testing without affecting quality rating
Read-only	GET endpoints only	Analytics, reporting, monitoring

Rotating Keys

For security, rotate your API keys regularly:

1. Generate a new key
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key from Settings → API Keys → Revoke

Request Format

All API requests must include:

curl -X POST https://api.startmessaging.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: unique-request-id" \
  -d '{ ... }'

Required Headers

Header	Value	Description
Authorization	Bearer <key>	Your API key
Content-Type	application/json	Request body format

Optional Headers

Header	Value	Description
X-Request-ID	UUID	Idempotency key for deduplication
X-Webhook-URL	URL	Override webhook URL for this request

Rate Limits

API rate limits are per API key:

Plan	Requests/second	Daily limit
Free	10	1,000
Premium	100	100,000
Enterprise	Custom (up to 1,000)	Unlimited

When rate-limited, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 1 second.",
    "retry_after": 1
  }
}

Security Best Practices

1. Never expose API keys in client-side code — use a backend proxy
2. Use environment variables — don’t hardcode keys in source code
3. Rotate keys regularly — at least every 90 days
4. Use IP allowlists — restrict API key usage to known server IPs (Settings → Security)
5. Monitor usage — set up alerts for unusual activity in your dashboard

Webhook Authentication

When receiving webhooks, verify the signature:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

FAQ

Can I have multiple API keys? Yes — you can create up to 10 API keys per account. Each key can have different permissions and labels for tracking.

What happens if my API key is compromised? Immediately revoke the compromised key from your dashboard and generate a new one. Contact support@startmessaging.com if you suspect unauthorized usage.