API Authentication

The TrolleyShield Public API uses API keys with Bearer token authentication.

API Keys

API keys are created and managed from your TrolleyShield dashboard under Settings → API Keys.

• Format: tsk_ followed by 32 random characters (e.g. tsk_a3f9d2e8b1c4f7...)
• Security: Keys are hashed (SHA-256) before storage — the full key is only shown once at creation
• Limit: Up to 10 active API keys per account
• Revocation: Keys can be revoked at any time from the dashboard

Tier Requirement

API keys require a paid plan (Forms, Starter, Growth, or Agency).

Using API Keys

Include your API key in the Authorization header as a Bearer token:

curl -X POST https://app.trolleyshield.com/api/v1/forms/analyze \
  -H "Authorization: Bearer tsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"form_data": {"name": "John Doe", "email": "john@example.com"}}'

Error Responses

All API endpoints return consistent error responses:

{
  "error": "Invalid or revoked API key"
}

HTTP Status	Error	Description
401	Missing or invalid Authorization header	No Bearer token provided
401	Invalid or revoked API key	Key doesn't exist or has been revoked
403	API access requires a paid plan	Account is on free or trial tier
400	Invalid request	Request body failed validation
429	Usage limit exceeded	Monthly limit reached (free/trial tiers only)
500	Internal server error	Something went wrong on our end

CORS

The public API supports cross-origin requests (CORS) with the following headers:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization