Documentation
search

Authentication & API Keys

Generate scoped API keys in the console and sign every request.

Every API request is authenticated with a scoped API key and signed with a timestamp. Keys are created in the console, tied to a single event, limited to the permissions you choose, and set to expire automatically.

Getting an API key

  1. In the console, open your event and go to Integrations → API Access.
  2. Under Permissions, choose what the key may do for each data type - No access, Read only, or Read & write.
  3. Generate one of two key types:
    • A 24-hour AI key - short-lived, ideal for pasting into an AI assistant or a one-off task.
    • A long-lived integration key (1 or 2 years) - for a permanent integration.
  4. Download the .env file. It contains the base URL, your client ID, event ID, and the key, plus a ready-to-run example request. The key is shown only once - store the file safely.

Keys can be revoked at any time from the same page. Revoking a key blocks it immediately.

The downloaded .env looks like this:

EVENTVAULT_API_BASE_URL=https://api.event-vault.com
EVENTVAULT_CLIENT_ID=your-client-id
EVENTVAULT_EVENT_ID=your-event-id
EVENTVAULT_API_KEY=evk_your-client-id_xxxxxxxxxxxxxxxxxxxxxxxx

Authentication headers

Every request must include the following HTTP headers:

Header Required Description
x-api-key ✓ Your API key (EVENTVAULT_API_KEY). Keep this secret.
x-client-id ✓ Your client ID as shown in the console (EVENTVAULT_CLIENT_ID).
x-event-id ✓ The ID of the event you want to manage (EVENTVAULT_EVENT_ID). Must match the event the key was issued for.
x-timestamp ✓ Current Unix timestamp in milliseconds (e.g. Date.now()). Must be within 5 minutes of server time.

Permissions (scopes)

Keys are scoped per object type so you can grant exactly what an integration needs - for example, a key that can edit speakers but only read attendees. Each type has a :read and a :write scope, chosen with the per-type selectors in the console. A request is rejected with 403 if the key is missing the scope an endpoint requires.

Object type Read scope Write scope Status
Guests attendees:read attendees:write Available
Tickets tickets:read tickets:write Available
Speakers speakers:read speakers:write Available
Sessions sessions:read sessions:write Available
Sponsors sponsors:read sponsors:write Available

Response codes

Write endpoints return plain-text bodies; read endpoints return JSON. Always check the HTTP status code first. These codes apply to every endpoint:

Status Meaning Typical cause
200 OK Success Operation completed successfully
400 Bad Request Missing required fields A required header, body field, or query parameter was omitted
403 Forbidden Not authorized Invalid, expired, or revoked key; key lacks the required scope; or key was issued for a different event
404 Not Found Resource not found Client, event, guest, ticket, or speaker does not exist
408 Request Timeout Timestamp out of range x-timestamp is more than 5 minutes from server time
409 Conflict Conflict with existing state e.g. guest already registered
429 Too Many Requests Rate limit exceeded Too many requests in a short window - retry after a brief pause
500 Internal Server Error Unexpected server error An unhandled error occurred on the server

Each key is rate-limited (currently 300 requests per minute). Exceeding the limit returns 429; pause briefly and retry.

Signing a request

Add the four headers to every call. The x-timestamp value is the current time in milliseconds - regenerate it for each request.

# Load the values from your .env file
set -a; source ./your-event.env; set +a

curl "$EVENTVAULT_API_BASE_URL/getGuestCount" \
  -H "x-api-key: $EVENTVAULT_API_KEY" \
  -H "x-client-id: $EVENTVAULT_CLIENT_ID" \
  -H "x-event-id: $EVENTVAULT_EVENT_ID" \
  -H "x-timestamp: $(date +%s%3N)"

With the key in place, continue to Guests, Tickets, or Speakers.

AI Quick Start →