Authentication

All REST API requests require a Bearer token in the Authorization header.

API keys

Create keys at /integrations. Keys have the prefix stp_rest_ followed by 64 hex characters.

curl https://sharetopus.com/api/v1/posts \
  -H "Authorization: Bearer stp_rest_YOUR_KEY"

Key properties

Security best practices

• Store keys in environment variables, never in source code.
• Rotate keys periodically. Revoke any key you suspect is compromised.
• Use HTTPS for all requests. The API rejects plain HTTP.

Rate limits

Each endpoint has per-principal rate limits. When exceeded, the API returns 429 Too Many Requests with a retry_after_seconds field.

Error responses

All errors follow a consistent shape:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  },
  "request_id": "req_abc123"
}

Error codes: unauthorized, forbidden, not_found, validation_error, rate_limited, internal_error.