API key authentication
API key authentication is how you prove that a request belongs to your account before calling the API. Every request requires an access key, sent in the x-access-key header for direct HTTP calls or supplied through configuration when you use a client library. Before you build posting, scheduling, or analytics flows on top of a key, verify your key with the health check endpoint so a missing or mistyped credential fails fast, in a dedicated check, instead of inside a later workflow.
API Key
All API requests require an access key. For a direct HTTP request, send the key in the x-access-key header. When you use a client library, the key can instead come from the documented API-key environment variable or be passed in the client constructor, which is the better choice when you want the credential to stay out of source code and request-building logic. Choose the header when you are writing raw HTTP, debugging with curl, or need explicit control over every request. Choose the environment variable when the same key is reused across scripts and services and should be injected by your deployment environment. Choose the constructor when a single application creates one client and you want the key scoped to that client instance. In every case, treat the key as a secret: do not commit it, do not log it, and rotate it if you suspect it has leaked. You can find your API key in the dashboard.
Verify Your Key
To verify your key, call the health check endpoint and confirm the response before making other calls. A successful verification returns a JSON body with ok set to true. Run this check after creating a new key, after rotating a key, after changing environment configuration, and whenever a request unexpectedly fails authentication. If the key is invalid, you will get a 401 or 403 response instead of the success body. The worked example in the code examples below shows the exact request and response; it is an illustrative example, not a claim that a live call was executed for you.
Failure Matrix: 401 and 403
Treat 401 and 403 as stop signs, not as errors to retry blindly. First, confirm that the x-access-key header is present and that the value has no surrounding whitespace, quotes, or placeholder text such as YOUR_API_KEY left in place. Second, confirm you are using the current key from the dashboard rather than an old or rotated value, and that the environment variable or constructor argument is actually reaching the client in the environment where the request runs. Third, re-run the health check endpoint in isolation: if it still returns 401 or 403, the problem is the key itself, not the endpoint you were calling. Only after the health check returns ok true should you retry the original request. Retrying a publishing call with a known-invalid key will not fix authentication and can mask the real problem.
Credits
Authentication is separate from quota, but the two meet as soon as you publish or schedule. Each API call that publishes or schedules a post consumes 1 credit, while failed posts do not count against your quota. That distinction matters when you design retries: a failed attempt should not burn quota, but a successful publish or schedule will. Keep credit consumption in mind when you batch or retry work, and check your usage before running large publishing jobs so you do not discover a quota limit mid-run.
Rate Limits
Rate limits depend on your plan. The API respects each platform's native rate limits and queues posts automatically to avoid throttling, so a burst of publishing requests may be queued rather than rejected outright. Because numeric limits are plan-dependent, do not hard-code assumptions about how many requests you can send at once. Instead, design clients to tolerate queuing, surface queued or delayed results clearly to users, and back off rather than hammering the API when responses slow down. Before a large job, confirm your plan's limits and your remaining credits, then verify your key so the job starts from a known-good credential.
Implementation Checklist
Use this checklist before your first real call. One, obtain your API key from the dashboard and store it in the documented API-key environment variable or pass it to the client constructor, reserving the x-access-key header for raw HTTP calls. Two, call the health check endpoint and confirm the response is ok true. Three, if you receive 401 or 403, fix the key and re-verify before proceeding. Four, confirm your credits and plan rate limits cover the work you intend to do, remembering that each publishing or scheduling call consumes 1 credit and failed posts do not count. Five, only then connect a social account and publish or schedule your first post.
| Input | Location | Required | Purpose |
|---|---|---|---|
| x-access-key | Request header | Yes | Access key authenticating the request |
| API-key environment variable | Environment variable read by client libraries | Alternative to header | Supplies the access key to SDK-based clients |
| Client constructor argument | Client initialization | Alternative to header | Supplies the access key to a specific client instance |
| GET {{API_BASE_URL}}/v1/health/auth | Request line | Yes, for verification | Health check endpoint used to verify your key |
| ok | Response field (boolean) | Returned on success | true indicates the key is valid |
Parity specification from captured source; origin shown as {{API_BASE_URL}}.
| Status | Meaning | Reader action |
|---|---|---|
| 401 | Invalid key | Check the x-access-key value, confirm the current key from the dashboard, and re-run the health check endpoint |
| 403 | Invalid key | Confirm the key is current and correctly configured via header, environment variable, or constructor, then re-verify before retrying other calls |
| {"ok": true} | Key verified | Proceed with other API calls using the same key |
Parity specification from captured source.
curl {{API_BASE_URL}}/v1/health/auth \
-H "x-access-key: YOUR_API_KEY"{
"ok": true
}curl -H "x-access-key: YOUR_API_KEY" \
{{API_BASE_URL}}/v1/health/auth