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 a client secret?

A client secret (vela_cs_...) authenticates all management operations — creating apps, registering schemas, configuring notification rules, rotating API keys. It has full account access and must only be used in server-side code, CI/CD pipelines, and the Vela CLI. Never put a client secret in frontend JavaScript, mobile app bundles, or public repositories.

​
Format

vela_cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Generating a client secret

1

Open the dashboard

Log into the Vela dashboard and go to Settings → Client Secrets.
2

Generate

Click Generate New Secret. Give it a label so you can identify it later (e.g. production-ci).
3

Copy immediately

Copy the full value now — it is shown only once. Vela stores only a hashed version internally.
4

Store securely

Add it to your secret manager, CI/CD environment variables, or .env file (which must be in .gitignore).
If you lose a client secret, revoke it and generate a new one — there is no way to retrieve the original value.

​
Using a client secret

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

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

// List all apps
const apps = await client.apps.list();

// Work with a specific app
const app = client.forApp('order-service');

// Create a schema
await app.schemas.create({
  eventName: 'order.placed',
  fields: [
    { id: 'f1', name: 'orderId',     type: 'string', required: true },
    { id: 'f2', name: 'amountCents', type: 'number', required: true },
  ],
});

// Create a notification rule
await app.notificationRules.create({
  name: 'Alert on payment failure',
  eventName: 'payment.failed',
  conditions: [],
  actions: [
    { id: 'a1', destinationId: 'dest-uuid', channel: 'slack', enabled: true },
  ],
});

​
Using in CI/CD

For GitHub Actions, store the secret as a repository secret: 
# .github/workflows/deploy.yml
- name: Push schemas to Vela
  run: npx @vela-event/cli push
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}
For other platforms:
PlatformWhere to configure
VercelProject → Settings → Environment Variables
RailwayService → Variables
RenderService → Environment
Fly.iofly secrets set VELA_CLIENT_SECRET=vela_cs_...
AWSSecrets Manager or SSM Parameter Store

​
Zero-downtime rotation

You can have multiple active client secrets simultaneously. Use this to rotate without interruption:
  1. Generate a new secret in the dashboard
  2. Update all services and CI/CD pipelines to use the new secret
  3. Deploy and verify services are healthy
  4. Revoke the old secret

​
Revoking a client secret

  1. Go to Settings → Client Secrets in the dashboard
  2. Click the delete icon next to the secret
  3. Confirm — revocation is instant and irreversible
Any service using a revoked secret immediately starts receiving 401 Unauthorized. Rotate to a new secret before revoking to avoid downtime.