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.