Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velahq.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
What is an API key?

An API key (vela_live_...) is the credential your application uses when calling POST /v1/ingest. It is scoped to a single app — it can only ingest events into that app and has no access to any management endpoints. This scope is intentional. Your API key lives in production services and is sent with every event. Even if it is compromised, the worst case is fake events being ingested — an attacker cannot read data, modify schemas, or access other apps.

​
Format

vela_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
How API keys are created

An API key is generated automatically when you create an app. The full key is shown once — at creation time only. 
import { VelaManagementClient } from '@vela-event/sdk';

const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);

const { app, apiKey } = await client.apps.create({ name: 'Order Service' });

console.log(app.slug); // "order-service"
console.log(apiKey);   // "vela_live_..." — save this immediately
The full API key is returned only at creation and during rotation. Store it in your secret manager immediately — Vela stores only a hashed version and cannot recover the original.

​
Using an API key

import { VelaIngestClient } from '@vela-event/sdk';

const ingest = new VelaIngestClient(process.env.VELA_API_KEY!);

// Single event
const result = await ingest.ingest({
  event: 'order.placed',
  data: { orderId: 'ord_abc123', amountCents: 4999, currency: 'USD' },
  level: 'info',
  customer_id: 'cust_42',
});

console.log(result.accepted);     // 1
console.log(result.events[0].id); // "evt_01j9..."

// Batch — up to 100 events per request
const batch = await ingest.ingest([
  { event: 'order.placed',   data: { orderId: 'ord_1', amountCents: 1999 }, level: 'info' },
  { event: 'payment.failed', data: { orderId: 'ord_2', reason: 'card_declined' }, level: 'error' },
]);

console.log(batch.accepted); // 2

​
Rotating an API key

Rotate a key if it is compromised or as part of regular security hygiene. The old key is revoked instantly on rotation. 
const { app, apiKey } = await client.apps.rotateKey('order-service');

console.log(apiKey); // new key — update your services now
// Previous key is immediately invalid
Rotation is instant and irreversible. If multiple services share an API key, update all of them. A brief window of 401 Unauthorized errors is expected between rotation and deployment.

​
Viewing existing apps

The full key value is not shown after creation. You can list apps and see masked hints: 
const apps = await client.apps.list();
for (const app of apps) {
  console.log(`${app.name} — ${app.apiKeyHint}`);
  // "Order Service — vela_live_abc1..."
}
If you need the full key, rotate it to receive a new one.