API Keys.

How to authenticate programmatic integrations with Vericto: available scopes, key lifecycle, CI/CD integration, and security best practices.

Overview

API keys are the authentication mechanism for non-interactive integrations: CI/CD pipelines, automation scripts, the Vericto CLI, and any system that needs to evaluate queries or read the audit trail without a human user behind it.

Each key has a set of scopes that defines exactly what it can do. A key with only the ci scope cannot read the audit trail or access the dashboard. This allows you to apply the principle of least privilege to each integration.

The key plaintext is shown only once. When creating a key, copy it and save it in your secrets manager before closing the window. Vericto only stores the hash and cannot recover the original value.

Available scopes

Each key can have one or more scopes. Assign only the ones the integration needs:

Scope What it allows Typical use case
ci Run the CLI dry-run in CI mode: evaluates queries against the ruleset without modifying the database. GitHub Actions, GitLab CI, Jenkins — validate queries before a deploy.
proxy Authenticate the Vericto TCP proxy to report intercepted query telemetry to the backend. The proxy container in Docker/Kubernetes. Requires VERICTO_API_KEY.
telemetry:write Send query events directly to the POST /api/v1/ingest/events endpoint. HTTP integrations that send telemetry without going through the TCP proxy.
audit:read Read the audit trail via API: list events, filter by date range and status. Compliance scripts that export the audit trail to a SIEM or data warehouse.
rules:read Query the active workspace ruleset. Inventory tools that need to know the active rules without dashboard access.

Key lifecycle

Create

Go to Dashboard → API Keys → New API key. Give it a descriptive name (e.g. GitHub Actions CI), select the required scopes, and optionally set an expiration in days. When created, copy the key — it is only shown once.

Rotate

Rotation generates a new key with the same scopes and immediately revokes the previous one. Use it for periodic rotation without interrupting service: update the secret in your CI/CD before confirming the rotation in Vericto, or do it in the same deployment window.

Revoke

Revocation is permanent and irreversible. The key stops working immediately. Use it when a key has been compromised or when the integration is no longer needed. If you just want to replace it, use Rotate instead.

Automatic expiration

You can set a TTL in days when creating the key (e.g. 90 days). After that period, the key expires automatically. Vericto does not send an expiration notification — schedule the rotation before the deadline. The Expires field in the dashboard shows the exact date.

CI/CD integration

The most common use case is validating SQL queries before a deploy in the CI pipeline. The Vericto CLI evaluates each query in the migration or seeds file against the active ruleset and fails the build if it detects any destructive ones.

GitHub Actions

# .github/workflows/vericto-check.yml
name: Vericto SQL check
on: [pull_request]

jobs:
  vericto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Vericto dry-run
        env:
          VERICTO_API_KEY: ${{ secrets.VERICTO_API_KEY }}
          VERICTO_WORKSPACE_ID: ${{ vars.VERICTO_WORKSPACE_ID }}
        run: |
          npx vericto-cli check \
            --file migrations/latest.sql \
            --dialect postgres \
            --workspace $VERICTO_WORKSPACE_ID

Store the API key as a secret in your repository (VERICTO_API_KEY), not as a public environment variable. The VERICTO_WORKSPACE_ID can be a public variable since it is not a secret.

Security best practices

Store the plaintext in a secrets manager

Never store the plaintext of an API key in source code, in .env files committed to the repository, or in internal documentation as plain text. Use your secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets, 1Password Teams) from the start.

One key per integration, minimum scopes

Create a separate key for each integration and assign only the scopes that integration needs. The CI pipeline only needs ci. The TCP proxy only needs proxy. If a key is compromised, the blast radius is limited to that key's scopes.

Periodic rotation

Rotate all API keys at least every 90 days, or immediately if you suspect one has been compromised. The rotation process in Vericto is atomic: the new key is valid before the old one stops working, if you manage the rotation correctly in your CI/CD.

Engineer offboarding

API keys are not associated with an individual user — they belong to the workspace. However, when someone who had access to the keys leaves the team, rotate all active keys as a precaution, especially if they have access to audit:read or rules:read.

Frequently asked questions

How many API keys can I have?

There is no limit on the number of API keys per workspace on any plan. Create as many as you need — one per integration is the recommended practice.

Can I see the value of a previously created key?

No. Vericto stores only the SHA-256 hash of the plaintext. If you lose the key, create a new one (you can use Rotate to keep the same scopes) and update the secret in your integration.

Do API keys have access to the browser dashboard?

No. API keys only authenticate calls to the Vericto REST API. You cannot log in to the dashboard with an API key — that requires email/password or SSO authentication.

How do I know if a key is being used?

The dashboard shows the last used date for each key in the API Keys list. For the TCP proxy, each intercepted query appears in the audit trail with the database_id associated with the key.

Who can create and manage API keys?

Only workspace owners and admins can create, rotate, and revoke API keys. Members and viewers do not have access to this section.