Reference

Authentication

Every request to the SocialSpool public API must be authenticated with a workspace API key sent as a bearer token. Writes also accept an Idempotency-Key header so retries are safe.

Bearer token

Send API keys with Authorization: Bearer <api_key>. Keys start with the prefix ssp_live_ followed by a base64url-encoded random secret.

Full keys are shown once at creation time and are never returned by any endpoint afterwards. Store the token immediately in a secret manager; lost keys must be revoked and replaced.

Required headers
  • Authorization: Bearer <api_key>: required on every request.
  • Content-Type: application/json: required on requests with a body.
  • Idempotency-Key: <string>: strongly recommended on write endpoints. The same key plus the same request body returns the original response for 24 hours.
Verifying credentials

The fastest way to confirm a key works is to call GET /api/v1/me. A successful response returns the workspace and key metadata that the request was authorized as.

curl "$SOCIALSPOOL_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $SOCIALSPOOL_API_KEY"

Successful response shape:

{
  "workspace": {
    "id": "ws_...",
    "name": "Acme Social",
    "plan": "creator"
  },
  "api_key": {
    "id": "key_...",
    "name": "Production pipeline",
    "scopes": ["posts:read", "posts:write", "accounts:read"]
  }
}
Authentication failures

Missing, invalid, revoked, or expired keys return 401 with a stable code value so you can distinguish them programmatically:

  • AUTHENTICATION_REQUIRED: no Authorization header or empty bearer value.
  • INVALID_API_KEY: the key is not recognized.
  • API_KEY_REVOKED: the key was revoked. Issue a new one.
  • API_KEY_EXPIRED: the key passed its expiry. Issue a new one.

See the Errors page for the full list of error codes.