API Authentication

Generating an API key

API keys are created in the Max Socials dashboard. Navigate to Settings → API Keys → New Key. Give the key a descriptive name (e.g. ci-deploy or crm-integration), then click Generate. The key is shown only once; copy it to a secrets manager immediately. You can revoke or regenerate any key from the same screen at any time.

Authenticating requests

Pass the key as a Bearer token in the Authorization header on every request:

Authorization: Bearer <your-api-key>

cURL

curl https://api.maxsocials.com/v1/batches \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const res = await fetch("https://api.maxsocials.com/v1/batches", {
  headers: {
    Authorization: `Bearer ${process.env.MAX_SOCIALS_API_KEY}`,
    "Content-Type": "application/json",
  },
});
const data = await res.json();

Python (requests)

import os, requests

resp = requests.get(
    "https://api.maxsocials.com/v1/batches",
    headers={"Authorization": f"Bearer {os.environ['MAX_SOCIALS_API_KEY']}"},
)
data = resp.json()

Key scopes

Max Socials uses a single-scope model today: a key either has access or it does not. Granular scopes (read, write, admin) are on the roadmap and will be introduced as a non-breaking opt-in. When scopes ship, existing keys will default to write (all current permissions) with no action required.

Rate limits

The default rate limit is 60 requests per minute per API key. Every response includes three tracking headers:

• X-RateLimit-Limit: your current limit (e.g. 60)
• X-RateLimit-Remaining: requests left in the current window
• X-RateLimit-Reset: Unix timestamp when the window resets

When you exceed the limit the API returns 429 Too Many Requests. Back off until X-RateLimit-Reset and retry. Higher limits are available on the Scale and Enterprise plans; contact support@maxsocials.com.

Error response shape

All API errors return a consistent JSON envelope regardless of HTTP status code:

{
  "error": {
    "code": "unauthorized",
    "message": "API key is missing or invalid.",
    "request_id": "req_01HZ9K..."
  }
}

Include request_id in any support request; it lets the team trace the full server-side log for that call instantly.

Rotating keys safely

Rotate a key without downtime in three steps:

1. Create a new key in Settings → API Keys. Both the old and new key are valid simultaneously.
2. Deploy the new key to your environment (update your secrets manager, redeploy your service, verify traffic is flowing with the new key).
3. Revoke the old key once you confirm the new one is healthy. Revocation is immediate and irreversible.

Aim to rotate keys every 90 days or immediately after any suspected exposure. If a key is compromised, revoke it first, then follow the three steps above to issue a replacement.