Skip to main content

Authentication

All API requests to Eventicat must be authenticated using your API key. We support two authentication methods to fit different use cases.

Getting Your API Key​

  1. Log in to your Eventicat dashboard
  2. Navigate to your account settings
  3. Find your API key in the API section
  4. Keep your API key secure - treat it like a password!
warning

Never commit your API key to version control or share it publicly. If your key is compromised, regenerate it immediately from your account settings.

Authentication Methods​

Method 1: URL Parameter (Simplest)​

Pass your API key as a URL parameter using _apikey. This is the easiest method for quick integrations and testing.

Example:

GET https://app.eventicat.com/api/event?_id=YOUR_AGGREGATOR_ID&_apikey=YOUR_API_KEY&name=user_signup

Pros:

  • Simple to implement
  • Works with basic HTTP clients
  • No header configuration needed

Cons:

  • API key visible in URLs and logs
  • Less secure for production environments

Pass your API key in the Authorization header as a Bearer token. This is the recommended method for production applications.

Example:

curl -X POST "https://app.eventicat.com/api/event?_id=YOUR_AGGREGATOR_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_signup"}'

Pros:

  • More secure (not visible in URLs)
  • Industry standard practice
  • Keeps API key out of logs

Cons:

  • Requires header support
  • Slightly more complex to implement

Required Parameters​

In addition to authentication, every request must include:

  • _id - Your aggregator ID (obtained when creating an aggregator)
  • _apikey - Your API key (if using URL parameter method)

Example Code​

JavaScript/TypeScript​

// Using fetch with Bearer token
const response = await fetch(
  `https://app.eventicat.com/api/event?_id=${AGGREGATOR_ID}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'user_signup'
    })
  }
);

Python​

import requests

# Using Bearer token
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

response = requests.post(
    f'https://app.eventicat.com/api/event?_id={AGGREGATOR_ID}',
    headers=headers,
    json={'name': 'user_signup'}
)

cURL​

# Using Bearer token (recommended)
curl -X POST "https://app.eventicat.com/api/event?_id=YOUR_AGGREGATOR_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_signup"}'

# Using URL parameter (simpler)
curl "https://app.eventicat.com/api/event?_id=YOUR_AGGREGATOR_ID&_apikey=YOUR_API_KEY&name=user_signup"

Error Responses​

401 Unauthorized​

Your API key is invalid or missing.

{
  "error": "Invalid API key"
}

Solution: Verify your API key is correct and hasn't been regenerated.

404 Not Found​

The aggregator ID is invalid or doesn't belong to your account.

{
  "error": "Invalid aggregator"
}

Solution: Verify the aggregator ID and ensure it belongs to your account.

Rate Limiting​

API requests are rate-limited per user account. When you exceed the rate limit, you'll receive a 429 Too Many Requests response with details:

{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "remaining": 0,
  "resetTime": 1640995200
}

Rate limit headers are also included in the response:

  • X-RateLimit-Limit - Total requests allowed in the time window
  • X-RateLimit-Remaining - Requests remaining in the current window
  • X-RateLimit-Reset - Timestamp when the limit resets

Best Practices​

  1. Use Bearer tokens in production - More secure and follows industry standards
  2. Store API keys securely - Use environment variables, never hardcode
  3. Regenerate compromised keys immediately - Available in account settings
  4. Monitor rate limits - Check response headers to avoid hitting limits
  5. Use HTTPS only - Never send API keys over unencrypted connections

Next Steps​