API authentication - Vibefollow

The SDK handles this for you. Read on if you’re calling the REST endpoints directly — from a language without an official SDK, or for ad-hoc curl debugging.

The header

Full request example

curl https://api.vibefollow.com/api/v1/events \
  -X POST \
  -H "Authorization: Bearer $VIBEFOLLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_user_id": "usr_42",
    "name": "user_signed_up",
    "properties": { "plan": "trial" }
  }'

await fetch('https://api.vibefollow.com/api/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIBEFOLLOW_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    external_user_id: 'usr_42',
    name: 'user_signed_up',
    properties: { plan: 'trial' },
  }),
});

A success response:

HTTP/1.1 202 Accepted
Content-Type: application/json

{ "data": { "accepted": true } }

202 Accepted confirms the event was enqueued, not that it has been fully processed. Vibefollow’s ingest pipeline is asynchronous — the event lands in your project’s event stream within a few hundred milliseconds.

Failure modes

401 Unauthorized

Header missing, malformed, or key revoked. Body: { "errors": [{ "code": "auth_required", ... }] }.

403 Forbidden

Key valid but doesn’t authorise access to the resource (e.g. wrong project).

422 Unprocessable Entity

Request body failed validation. errors[0].field names the offending field.

429 Too Many Requests

Rate limited. Respect the Retry-After header.

5xx Server error

Safe to retry — the Idempotency-Key prevents duplicates.

The full mapping to typed SDK errors is documented in Errors.

Idempotency in detail

The Idempotency-Key is required on every mutating request — the SDK auto-generates one if you don’t pass it. The backend dedupes within a 24-hour window keyed by (project_id, idempotency_key).

Scenario	Result
Same key + same body within 24h	Returns the original response (the second request is a no-op)
Same key + different body within 24h	Rejected with `422` (`code: "idempotency_key_reuse"`)
Same key after 24h	The key is forgotten; safe to reuse

Use a fresh UUID per logical write. Don’t share keys across unrelated events.

CORS

The API does not send Access-Control-Allow-Origin headers. The browser cannot call Vibefollow directly — build a server proxy if you need browser-originated events.

TLS

HTTPS only. Plaintext HTTP requests are refused at the edge with a redirect to https://. TLS 1.2+ required. We do not support TLS 1.0/1.1.

​The header

​Full request example

​Failure modes

​Idempotency in detail

​CORS

​TLS

The header

Full request example

Failure modes

Idempotency in detail

CORS

TLS