Skip to main content

​
Overview

UserBoost uses API keys for server-side authentication. All API requests must include a valid API key in the Authorization header.

​
Event Format for Authentication

UserBoost accepts events in a simple, flexible format:

​
Required Fields

  • Event name: "event": "your_event_name"
  • User object: "user": {"id": "user_id", ...} (must be object with id field)

​
User Object Format

UserBoost requires user data to be provided as an object: Minimal user object (required): 
{
  "event": "user_signed_up",
  "user": {
    "id": "user_123"
  }
}
User object with additional data: 
{
  "event": "user_signed_up",
  "user": {
    "id": "user_123",
    "email": "john@example.com",
    "traits": {
      "plan": "free",
      "created_at": "2025-01-15"
    }
  }
}
Important: String format like "user": "user_123" is no longer supported and will result in validation errors.

​
Optional Fields

  • Properties: "properties": {...} - Event-specific data
  • Timestamp: Server generates automatically if not provided
  • Context: IP, User-Agent automatically extracted from HTTP headers

​
API Key Format

API keys use specific prefixes to indicate their environment:
  • Live Keys
Format: ub_live_* ub_live_xyz789uvw012345678901234567890abcdef
  • Used for production traffic - Trigger real email sends - Count towards billing limits - Should only be used in production

​
Authentication Header

Include your API key in the Authorization header using Bearer authentication: 
curl -X POST https://api.userboo.st/v1/event \
  -H "Authorization: Bearer $USERBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user_signed_up",
    "user": {
      id: "xxx"
    },
    "properties": {
      "email": "john@example.com",
      "plan": "free"
    }
  }'

​
Creating API Keys

1

Sign Up

Create your account at userboo.st
2

Navigate to API Keys

Go to Settings → API Keys in your dashboard
3

Create New Key

Click “Create New API Key” and choose: - Name: Descriptive name (e.g., “Production Website”) - Type: Test or Live environment
4

Copy and Store

Copy the API key immediately - it won’t be shown again!
API keys are only shown once during creation. Make sure to copy and securely store your key immediately.

​
Security Best Practices

​
Environment Management

  • Store API keys in environment variables
  • Use test keys in development/staging
  • Use live keys only in production
  • Rotate keys every 90 days
  • Use different keys for different projects
  • Monitor key usage in your dashboard
  • Commit API keys to version control
  • Share keys via email or chat
  • Use live keys in development
  • Hardcode keys in source code
  • Use the same key across multiple environments
  • Log API keys in application logs

​
Key Rotation

To rotate an API key safely:
1

Create New Key

Generate a new API key in your dashboard
2

Update Environment

Update your environment variables with the new key
3

Deploy Changes

Deploy your application with the new key
4

Test Integration

Verify events are being received correctly
5

Delete Old Key

Remove the old key from your dashboard

​
Error Responses

​
Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}
HTTP Status: 401 Unauthorized Common causes:
  • API key is incorrect or malformed
  • API key has been revoked
  • Wrong key type (test vs live)
  • Missing ub_live_ or ub_live_ prefix

​
Missing Authorization Header

{
  "success": false,
  "error": {
    "code": "MISSING_AUTH_HEADER",
    "message": "Missing or invalid authorization header"
  }
}
HTTP Status: 401 Unauthorized Common causes:
  • No Authorization header provided
  • Header doesn’t start with “Bearer ”
  • Empty or whitespace-only header value

​
Invalid Key Format

{
  "success": false,
  "error": {
    "code": "INVALID_KEY_FORMAT",
    "message": "API key must start with ub_live_ or ub_live_"
  }
}
HTTP Status: 401 Unauthorized Solution: Ensure your API key uses the correct prefix format.

​
Testing Authentication

​
Verify Your Setup

Test authentication with a simple API call: 
curl -X POST https://api.userboo.st/v1/event \
  -H "Authorization: Bearer $USERBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth_test",
    "user": "test_user"
  }'

​
Expected Success Response

{
  "success": true,
  "data": {
    "processed_count": 1,
    "failed_count": 0,
    "results": [
      {
        "index": 0,
        "success": true,
        "event_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }
}

​
Rate Limits

API key-based rate limiting is applied per minute based on your subscription plan:
PlanPriceAPI Requests/MinuteEvent Limit/MonthEmail Limit/Month
HobbyFree1001,000100
Launch$25/month1,00020,0005,000
Orbit$79/month10,000200,00025,000
Rate limits are applied per account based on your active subscription. All API keys under your account share the same rate limit.

​
Rate Limit Headers

All API responses include rate limit information: 
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400
X-RateLimit-Window: 60
  • X-RateLimit-Limit: Maximum requests allowed per minute
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets
  • X-RateLimit-Window: Window duration in seconds (always 60)

​
Rate Limit Exceeded

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "details": {
      "limit": 100,
      "window_seconds": 60,
      "retry_after_seconds": 45,
      "requests_remaining": 0
    }
  }
}
HTTP Status: 429 Too Many Requests Response Headers: 
Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642694460
X-RateLimit-Window: 60
⌘I