Documentation
An API key lets a script, the Veltrix CLI, a CI/CD job or an AI assistant act on your organization without a person signing in. Every key belongs to one organization and is bound to an RBAC role: the key can do exactly what that role allows, and nothing else. A key without a role is rejected (fail-closed).
Role design, the permission matrix and single sign-on are covered in Access Control & Single Sign-On. This page covers the keys themselves.
/settings/keys-token. The page title is “API Keys & Tokens”.apiKey:read to list keys, apiKey:write to create or delete them. Without apiKey:write the Create New Key button and the Delete action are hidden.| Setting | Options and rules |
|---|---|
| Key Name | Required, 3–64 characters. |
| Key Type | API Key or Admin Key in the portal. A third type, webhook, exists for inbound webhook delivery (see Webhook keys) and appears in the list but is not offered in the create form. The type is a label; what a key can do comes from its role. |
| Access Role | Required. Must be a role in your own organization. You can only bind a key to a role whose permissions you hold yourself; otherwise creation is refused with an explanation of the missing permissions. |
| Expiration | Never, 30, 90, 180 or 365 days from creation. |
Keys are vltx_ followed by 43 random characters, so a leaked key is easy for secret scanners to recognise.
| Column | Meaning |
|---|---|
| Name | The name you gave the key. |
| Type | Admin, API or Webhook badge. |
| Role | The role the key is bound to. |
| Key | A masked value: the non-secret prefix (for example vltx_ab12cd) followed by dots. Use it to tell keys apart. |
| Created / Last Used | Timestamps. Last Used shows “Never” until the key authenticates a request. |
| Expires | The expiry date, or “Never”. |
| Actions | Delete (with apiKey:write). |
If the list cannot load you get an error with a Retry link. An empty list says “No API keys found”.
Select Delete and confirm. Deleting is permanent and cannot be undone; anything still using the key starts failing with 401 immediately.
Send the key in the X-API-Key header (preferred) or as Authorization: ApiKey <key>:
curl https://app.veltrixsecops.com/api/configuration-canvas \
-H "X-API-Key: vltx_..."veltrix login; see CLI Reference./api/api-keys) needs a signed-in session — one key cannot create or delete other keys. The only exception is a key rotating itself (see Rotation).An expired key stops authenticating. The status reported by the API is one of active, expiring_soon, expired or revoked; a key is expiring soon within 30 days of its expiry date. Each day a background job closes lapsed rotation overlaps and evaluates keys against 30, 14, 7 and 1-day thresholds.
Do not rely on a reminder reaching you: set your own calendar reminder or watch the Expires column, and prefer a finite expiration for any key that leaves your control (CI systems, contractors, AI tooling).
Rotation lets you replace a key's secret without a hard cut-over. It is exposed through the API only; there is no rotate button in the portal. All paths are under /api.
| Call | What it does |
|---|---|
POST /api-keys/:id/rotate | Issue a new secret for the key and return it once. The previous secret keeps working for the grace window. Optional reason (up to 256 characters) is recorded in the audit trail. Needs a session with apiKey:write. |
PUT /api-keys/:id/auto-rotation | Enable or disable scheduled rotation. intervalDays 1–3650 (default 90), graceDays 0–90 (default 7). Enabling on a key with no expiry gives it one. |
GET /api-keys/rotation/status | Expiry and rotation status for the organization's keys. |
GET /api-keys/:id/rotation-history | Who rotated the key, when, and why. |
POST /api-keys/self/rotate | A key rotates itself (for integrations). Allowed only for keys enrolled in scheduled rotation, and it cannot extend the key's life beyond its existing schedule. |
GET /api-keys/self | Returns { valid, expiresAt } for the calling key. |
POST /api-keys/:id/regenerate, POST /api-keys/:id/revoke, PUT /api-keys/:id | Regenerate a key, revoke it, or update its name, expiry or scopes. |
Key-management calls are refused while a platform operator is impersonating your session.
AI assistants authenticate with an ordinary role-bound key. Bind it to the narrowest role the assistant needs (a read-only role means it cannot draft anything). MCP access is a paid-plan capability: tenants on the free plan are told to upgrade before connecting AI tooling. Full setup is in MCP Server, and the governance model is in AI Guardrails.
Veltrix accepts inbound webhook deliveries from external systems (for example CI or GitHub). There is no portal screen for webhooks; the only thing you manage in the portal is the key they authenticate with.
POST /api/webhooks (generic), POST /api/webhooks/github and GET /api/webhooks/health.X-API-Key. The key must be of type webhook or carry a webhooks:write scope. The organization is taken from the key, never from the payload.source, event and payload (and optionally timestamp and metadata).X-Hub-Signature-256 HMAC signature; a missing or invalid signature is rejected with 401. Deliveries are replay-protected by delivery ID and timestamp freshness.Webhook keys are created through the API (type webhook), then appear in the Keys & Tokens list with a Webhook badge. See REST API Reference for request details.