Authentication and scopes
Create, protect, and grant the minimum permissions to an organization API key.
Every Public API request must include an organization API key. A key belongs to one organization, so it can read only that organization's data.
Who can manage API keys
Organization owners and admins can create and revoke keys from the API Keys page.
When creating a key:
- Give it a name that identifies the client and environment, such as Acme CRM production.
- Select only the scopes the integration needs.
- Set an expiry when the integration has a known end date.
- Copy the secret immediately. MeraEvents does not show the complete secret again.
Revoking a key stops every integration using it. A revoked key cannot be restored; create a replacement instead.
Send the key
The recommended header is:
x-api-key: YOUR_SECRET_TOKENBearer authentication is also accepted:
Authorization: Bearer YOUR_SECRET_TOKENSend one style per request. Do not place the key in the query string.
Available scopes
| Scope | What it permits |
|---|---|
events:read | Events, agenda, venues, registration field definitions, categories, subcategories, countries, and cities |
tickets:read | Active ticket types, availability, and active discounts |
registrations:read | Successful registration records, attendee contact details, and submitted field values |
The registrations:read scope exposes attendee personal data and is not selected by default. Grant it only to systems that need registration data.
Scope required by each endpoint
| Method and path | Required scope |
|---|---|
GET /v1/events | events:read |
GET /v1/events/{eventId} | events:read |
GET /v1/events/{eventId}/sessions | events:read |
GET /v1/events/{eventId}/venues | events:read |
GET /v1/events/{eventId}/custom-fields | events:read |
GET /v1/categories | events:read |
GET /v1/subcategories | events:read |
GET /v1/countries | events:read |
GET /v1/cities | events:read |
GET /v1/events/{eventId}/tickets | tickets:read |
GET /v1/events/{eventId}/discounts | tickets:read |
GET /v1/events/{eventId}/registrations | registrations:read |
Organization isolation
The API verifies both the key and the organization on every request. If an event is deleted, does not exist, or belongs to another organization, the API returns 404. It does not reveal whether an event ID belongs to someone else.
Protect the key
- Store it in a secret manager or protected server environment variable.
- Never commit it to source control.
- Never send it to analytics, error tracking, or application logs.
- Use separate keys for production, staging, and different clients.
- Revoke a key immediately if it may have been exposed.
- Rotate keys without downtime by creating a replacement, deploying it, verifying traffic, and then revoking the old key.
Rate limit
Each key is limited to 120 requests per minute across the Public API. Cache event configuration where appropriate, paginate registration requests, and avoid polling unchanged data many times per second.
If the API returns 429, stop sending requests and retry later with backoff.
Next step
Make your first request using the Public API quickstart, then use the event ID it returns to read event-specific data.