Authentication

Keys, tokens, and access control

Ventryx uses API keys for server-to-server authentication. Learn how to create, scope, rotate, and revoke keys — and how organization-level access is structured.

API Keys

API keys are long-lived credentials that authenticate requests on behalf of your organization. Each key carries a set of scopes that determine what it can access.

Never expose API keys in client-side code, public repositories, or logs. Use environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or 1Password Secrets Automation.

Key format

vtx_live_a1b2c3d4e5f6...   ← Production key
vtx_test_a1b2c3d4e5f6...   ← Test / sandbox key

Creating a key

Keys can be created via the dashboard (Settings → API Keys → New Key) or via the API:

curl

curl -X POST https://api.ventryx.io/v1/api-keys \
  -H "Authorization: Bearer vtx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "scopes": ["workflows:read", "events:write"]
  }'

Response

{
  "data": {
    "id": "key_01HXYZ",
    "name": "ci-pipeline",
    "key": "vtx_live_a1b2c3d4e5f6...",
    "scopes": ["workflows:read", "events:write"],
    "created_at": "2026-04-02T10:00:00Z"
  }
}

The key value is only returned once at creation time. Store it securely immediately.

Scopes

Scopes follow a resource:action format. Assign only the scopes your integration actually needs.

Scope	Description
`workflows:read`	List and retrieve workflows
`workflows:write`	Create, update, and delete workflows
`events:read`	List and retrieve events
`events:write`	Emit events
`api-keys:read`	List API keys
`api-keys:write`	Create and revoke API keys
`org:admin`	Full organization-level access

Rotating keys

To rotate a key without downtime:

Create a new key with the same scopes via the dashboard or API.
Update your environment variables or secrets manager with the new key.
Deploy your updated configuration.
Revoke the old key once traffic has migrated.

Revoking keys

Revoke a key immediately to prevent further use:

curl

curl -X DELETE https://api.ventryx.io/v1/api-keys/key_01HXYZ \
  -H "Authorization: Bearer vtx_live_your_key_here"

Revocation is instantaneous. Any in-flight requests using the revoked key will return 401 Unauthorized.

Organization structure

All resources in Ventryx are scoped to an organization. A single organization can have multiple members, API keys, and environments (live / test). API keys are organization-scoped by default and can only access resources within their organization.