Client Secrets

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

Open the dashboard

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

Generate

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

Copy immediately

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

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:

Platform	Where to configure
Vercel	Project → Settings → Environment Variables
Railway	Service → Variables
Render	Service → Environment
Fly.io	`fly secrets set VELA_CLIENT_SECRET=vela_cs_...`
AWS	Secrets Manager or SSM Parameter Store

Zero-downtime rotation

You can have multiple active client secrets simultaneously. Use this to rotate without interruption:

Generate a new secret in the dashboard
Update all services and CI/CD pipelines to use the new secret
Deploy and verify services are healthy
Revoke the old secret

Revoking a client secret

Go to Settings → Client Secrets in the dashboard
Click the delete icon next to the secret
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.

Getting Started

Credentials

Client Secrets

What is a client secret?

Format

Generating a client secret

Using a client secret

Using in CI/CD

Zero-downtime rotation

Revoking a client secret

​What is a client secret?

​Format

​Generating a client secret

​Using a client secret

​Using in CI/CD

​Zero-downtime rotation

​Revoking a client secret

What is a client secret?

Format

Generating a client secret

Using a client secret

Using in CI/CD

Zero-downtime rotation

Revoking a client secret