Authentication

Overview

Authentication depends on the API surface:

Public API

Requires API key.Preferred header: x-evento-api-key

Embed API

No authentication required.CORS-enabled for browser access.

Never ship your Public API key in client-side JavaScript. Keep keyed requests server-side.

Public API headers

Primary option:

x-evento-api-key: YOUR_API_KEY

Alternative option:

Authorization: Bearer YOUR_API_KEY

Examples

curl https://evento.so/api/public/v1/events/evt_abc123 \
  -H "x-evento-api-key: YOUR_API_KEY"

curl https://evento.so/api/public/v1/events/evt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://evento.so/api/embed/v1/events/evt_abc123

const response = await fetch('https://evento.so/api/public/v1/events/evt_abc123', {
  headers: {
    'x-evento-api-key': process.env.EVENTO_API_KEY
  }
});

const data = await response.json();

import os
import requests

headers = {
    'x-evento-api-key': os.environ['EVENTO_API_KEY']
}

response = requests.get(
    'https://evento.so/api/public/v1/events/evt_abc123',
    headers=headers
)

data = response.json()

Error responses

401 unauthorized

Returned when the API key is missing, invalid, or revoked:

{
  "success": false,
  "message": "Not authenticated."
}

Common causes:

Missing x-evento-api-key header
Invalid API key format
Revoked or expired API key

403 forbidden

Returned when the key is valid but missing required permissions:

{
  "success": false,
  "message": "Insufficient API key scope."
}

429 too many requests

Returned when you exceed the rate limit (1,000 requests/day):

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

Response headers include:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

Best practices

Use environment variables

Store API keys in environment variables, never hardcode them

EVENTO_API_KEY=evento_xxx

Server-side only

Use keyed requests from trusted backend environments only.

Implement retry logic

Use exponential backoff when retrying failed requests

Handle errors gracefully

Always check for 401 and 429 responses and handle them appropriately

CORS notes (Embed API)

Embed API includes permissive CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Testing authentication

Use this simple request to verify your API key is working:

curl https://evento.so/api/public/v1/events/evt_test \
  -H "x-evento-api-key: YOUR_API_KEY" \
  -v

If the key is valid but the event does not exist, you will receive 404 instead of 401.

Essentials

Public API

Embed API

Guides

Overview

Public API

Embed API

Public API headers

Examples

Error responses

401 unauthorized

403 forbidden

429 too many requests

Best practices

Use environment variables

Server-side only

Implement retry logic

Handle errors gracefully

CORS notes (Embed API)

Testing authentication

Next steps

Get /events/{eventId}

Embed API

​Overview

Public API

Embed API

​Public API headers

​Examples

​Error responses

​401 unauthorized

​403 forbidden

​429 too many requests

​Best practices

Use environment variables

Server-side only

Implement retry logic

Handle errors gracefully

​CORS notes (Embed API)

​Testing authentication

​Next steps

Get /events/{eventId}

Embed API

Overview

Public API headers

Examples

Error responses

401 unauthorized

403 forbidden

429 too many requests

Best practices

CORS notes (Embed API)

Testing authentication

Next steps