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.

​
Two credential types

CredentialFormatScopeUsed for
Client secretvela_cs_...Account-levelCreating apps, managing schemas, configuring rules
API keyvela_live_...App-levelIngesting events into one specific app

​
Why two credentials?

Your API key is sent with every event your application ingests — it lives in your production services and travels over the network constantly. If it is ever leaked, an attacker can only ingest events into that one app. They cannot read your stored data, modify schemas, delete apps, or access anything else. Your client secret has full account access. It belongs only in server-side configuration, CI/CD secret stores, or the Vela CLI. Never put a client secret in frontend JavaScript, mobile apps, or public repositories.

​
Client secret

Used with the Management Client to authenticate account-level operations. 
import { VelaManagementClient } from '@vela-event/sdk';

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

const apps = await client.apps.list();
const app = client.forApp('order-service');
const schemas = await app.schemas.list();
Generate client secrets from Settings → Client Secrets in the dashboard. You can have multiple active secrets simultaneously — useful for zero-downtime rotation.

​
API key

Used with the Ingest Client to send events. Scoped to a single app. 
import { VelaIngestClient } from '@vela-event/sdk';

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

await ingest.ingest({
  event: 'order.placed',
  data: { orderId: 'ord_1', amountCents: 4999 },
  level: 'info',
});

​
Best practices

Store credentials in environment variables or your platform’s secret store.
# .env — add this to .gitignore
VELA_CLIENT_SECRET=vela_cs_...
VELA_API_KEY=vela_live_...
Use .env.sample with empty placeholder values for documentation.
Create a separate Vela app per environment. A leaked staging key then has zero impact on production.
order-service-prod    → VELA_API_KEY_PROD
order-service-staging → VELA_API_KEY_STAGING
  • API key — rotate from app settings. Old key revoked instantly.
  • Client secret — generate a new one first, update services, then revoke the old one.
Client secrets grant full account access. They must never appear in browser JavaScript, mobile app bundles, Docker images pushed to public registries, or application logs.
Credentials are shown in full only at creation time. If you lose one, revoke it and generate a new one — Vela stores only a hashed version internally.

​
Next steps

Client Secrets

Generate, use, and revoke client secrets.

API Keys

How API keys are created and rotated.