Headers & Auth

Authentication headers secure the connection between SellerShorts and your AI automation. You must configure at least one authentication header to verify that webhook requests come from our platform.

Overview

Outbound authentication (SellerShorts → your webhook): When buyers run your AI Short, we POST inputs to your webhook URL and include the headers you configure here (e.g., Authorization: Bearer or x-api-key). This lets your agent verify the request is from SellerShorts.

Inbound authentication (your system → SellerShorts): When you POST results to our callback URL, include the generated x-callback-secret. That secret is managed in the Connect step and is validated by SellerShorts.

Required authentication

Outbound (to your webhook): Add at least one header (Authorization: Bearer or x-api-key). We include these on every POST.

Inbound (your callback to us): Always include x-callback-secret from the Connect step.

Recommended header patterns

Authorization: Bearer (recommended)

• Format: Authorization: Bearer YOUR_TOKEN
• Best for: OAuth tokens, JWT tokens, modern API services
• Examples:
  • Authorization: Bearer example-token-123
  • Authorization: Bearer key_example_abc123
  • Authorization: Bearer your-workspace-token
• Platforms: Relevance AI, custom APIs, cloud functions

x-api-key (recommended)

• Format: x-api-key: YOUR_KEY
• Best for: Static API keys, gateway authentication
• Examples:
  • x-api-key: abc123def456ghi789
  • x-api-key: your-secret-api-key
• Platforms: AWS API Gateway, custom services, middleware

x-auth-token (alternative)

• Format: x-auth-token: YOUR_TOKEN
• Best for: Custom token authentication systems
• Use when: Your platform expects a different header name

Platform-specific guidance

Make.com

• Recommended: x-api-key: your-secret-key
• Setup: Add custom header in HTTP module settings
• Validation: Use Router module to check header value
• Example scenario: Check if header equals expected value, reject if not

n8n

• Recommended: Authorization: Bearer your-token
• Setup: Configure in Webhook node authentication tab
• Validation: Use IF node to validate header
• Best practice: Store token in environment variables

Relevance AI

• Recommended: Authorization: Bearer workspace-token
• Setup: Use your workspace or project API key
• Location: Found in your Relevance AI dashboard settings
• Format: Usually starts with your workspace identifier

Custom APIs/Cloud Functions

• Choice: Either Authorization: Bearer or x-api-key
• Implementation: Validate header in your function code
• Security: Use environment variables to store secrets
• Example: AWS Lambda, Vercel Functions, Google Cloud Functions

Security best practices

Token generation

• Use strong tokens – Generate cryptographically secure, random tokens
• Minimum length – At least 32 characters for custom tokens
• Character set – Use letters, numbers, and special characters
• Uniqueness – Generate unique tokens for each AI Short

Token management

• Store securely – Use environment variables, not hardcoded values
• Rotate regularly – Change tokens periodically (monthly/quarterly)
• Monitor usage – Watch for unusual authentication attempts
• Limit scope – Use tokens with minimal required permissions

Validation implementation

• Always validate – Check header value on every request
• Fail securely – Reject requests with missing/invalid headers
• Log failures – Record authentication failures for monitoring
• Rate limiting – Consider limiting requests from invalid sources

Multiple headers

You can add multiple authentication headers for enhanced security:

• Primary + backup – Use different authentication methods
• Layered security – Validate multiple tokens
• Migration – Support old and new tokens during rotation
• Platform-specific – Different headers for different environments

Example multi-header setup

Authorization: Bearer example-token-123
x-api-key: key_example_abc123

Testing authentication

Connection test validation

When you run the connection test in the Connect step:

1. Enable webhook – Make sure your endpoint is active
2. Check headers – Verify authentication header validation works
3. Test success – Green checkmark confirms headers are accepted
4. Test failure – 401/403 errors indicate header problems

Manual testing with cURL

curl -X POST "https://your-webhook-url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer example-token-123" \
  -d '{
    "short_id": "test123",
    "order_id": "test-order-uuid",
    "inputs": {
      "test_field": "test value"
    },
    "callback_url": "https://api.example.com/callback",
    "ts": 1736032405
  }'

Common authentication issues

401 Unauthorized errors

• Missing header – Add required authentication header
• Wrong header name – Check exact header name expected
• Invalid token – Verify token value is correct
• Token format – Ensure proper Bearer prefix if required

403 Forbidden errors

• Valid but insufficient – Token exists but lacks permissions
• Expired token – Refresh or regenerate authentication token
• Blocked source – Whitelist SellerShorts IP ranges if needed
• Rate limited – Check if too many requests are being blocked

Header configuration in SellerShorts

In the Connect step of the submission wizard:

1. Add header – Click "Add Header" button
2. Enter name – Type header name (e.g., "Authorization")
3. Enter value – Type full header value (e.g., "Bearer your-token")
4. Save configuration – Headers are saved with your AI Short
5. Test connection – Verify headers work before proceeding