API Keys

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

import os
from vela import VelaManagementClient

client = VelaManagementClient(os.environ["VELA_CLIENT_SECRET"])
result = client.apps.create({"name": "Order Service"})

print(result.app.slug)  # "order-service"
print(result.api_key)   # "vela_live_..." — save this immediately

curl -X POST https://api.velahq.xyz/v1/apps \
  -H "Authorization: Bearer vela_cs_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Order Service" }'

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

import os
from vela import VelaIngestClient

with VelaIngestClient(os.environ["VELA_API_KEY"]) as ingest:
    result = ingest.ingest({
        "event": "order.placed",
        "data": {"orderId": "ord_abc123", "amountCents": 4999},
        "level": "info",
    })
    print(result.accepted)      # 1
    print(result.events[0].id)  # "evt_01j9..."

curl -X POST https://api.velahq.xyz/v1/ingest \
  -H "x-api-key: vela_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.placed",
    "data": { "orderId": "ord_abc123", "amountCents": 4999 },
    "level": "info"
  }'

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

result = client.apps.rotate_key("order-service")
print(result.api_key)  # new key
# Previous key is immediately invalid

curl -X POST https://api.velahq.xyz/v1/apps/order-service/rotate-key \
  -H "Authorization: Bearer vela_cs_..."

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.

Getting Started

Credentials

What is an API key?

Format

How API keys are created

Using an API key

Rotating an API key

Viewing existing apps

​What is an API key?

​Format

​How API keys are created

​Using an API key

​Rotating an API key

​Viewing existing apps

What is an API key?

Format

How API keys are created

Using an API key

Rotating an API key

Viewing existing apps