Skip to main content

Authentication

All API requests to Eventkiwi 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 Eventkiwi dashboard
  2. Open any aggregator (or create one)
  3. Under Event Collection URL, click Show Request Examples (with your keys)
  4. Copy the key from either example — it is the value after _apikey= or Bearer

There is one API key per account, shared by all your aggregators. The aggregator ID (_id) is what tells Eventkiwi which aggregator an event belongs to.

warning

Treat your API key like a password: never commit it to version control or put it in client-side code. Keys cannot be rotated from the app yet, so if yours is exposed, email info@eventkiwi.com and we will replace it.

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.eventkiwi.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.eventkiwi.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.eventkiwi.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.eventkiwi.com/api/event?_id={AGGREGATOR_ID}',
    headers=headers,
    json={'name': 'user_signup'}
)

cURL​

# Using Bearer token (recommended)
curl -X POST "https://app.eventkiwi.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.eventkiwi.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​

Event submission is limited to 5 requests per second per user account. When you exceed it, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "limit": 5,
  "remaining": 0,
  "resetTime": 1640995201000
}

resetTime is a Unix timestamp in milliseconds. See Limits for the rate limit and your plan's event allowance.

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. Keep the key server-side - Proxy browser events through your own backend (see Language Examples)
  4. Pace your requests - Stay under 5 requests per second and back off on a 429
  5. Use HTTPS only - Never send API keys over unencrypted connections

Next Steps​