Skip to main content

​
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 },
  ],
});

import os
from vela import VelaManagementClient

client = VelaManagementClient(os.environ["VELA_CLIENT_SECRET"])

apps = client.apps.list()
app = client.for_app("order-service")

app.schemas.create({
    "event_name": "order.placed",
    "fields": [
        {"id": "f1", "name": "orderId",     "type": "string", "required": True},
        {"id": "f2", "name": "amountCents", "type": "number", "required": True},
    ],
})

export VELA_CLIENT_SECRET="vela_cs_..."
vela diff   # preview schema changes
vela push   # push local schemas to Vela

curl https://api.velahq.xyz/v1/apps \
  -H "Authorization: Bearer vela_cs_your_secret_here"

​
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.