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

# Client Secrets

> Account-level credentials for the Vela Management API. Used to create apps, manage schemas, and configure notification rules.

## 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

<Steps>
  <Step title="Open the dashboard">
    Log into the Vela dashboard and go to **Settings → Client Secrets**.
  </Step>

  <Step title="Generate">
    Click **Generate New Secret**. Give it a label so you can identify it later (e.g. `production-ci`).
  </Step>

  <Step title="Copy immediately">
    Copy the full value now — it is shown **only once**. Vela stores only a hashed version internally.
  </Step>

  <Step title="Store securely">
    Add it to your secret manager, CI/CD environment variables, or `.env` file (which must be in `.gitignore`).
  </Step>
</Steps>

<Warning>
  If you lose a client secret, revoke it and generate a new one — there is no way to retrieve the original value.
</Warning>

## Using a client secret

<CodeGroup>
  ```typescript TypeScript theme={null}
  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 },
    ],
  });
  ```

  ```python Python theme={null}
  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},
      ],
  })
  ```

  ```bash CLI theme={null}
  export VELA_CLIENT_SECRET="vela_cs_..."
  vela diff   # preview schema changes
  vela push   # push local schemas to Vela
  ```

  ```bash curl theme={null}
  curl https://api.velahq.xyz/v1/apps \
    -H "Authorization: Bearer vela_cs_your_secret_here"
  ```
</CodeGroup>

## Using in CI/CD

For GitHub Actions, store the secret as a repository secret:

```yaml theme={null}
# .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:

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.