API Keys

Project-scoped credentials the CLI and runtime use to read and write a vault. Shown once at creation; only a hash is stored.

What API keys are

An API key (vlt_…) authorizes access to a single project. The portal stores only a SHA-256 hash plus a non-sensitive prefix for display — the raw key is shown exactly once at creation and is never retrievable later.

Copy it immediately

When you create a key, copy it right away and store it in your secret manager. If you lose it, revoke it and create a new one.

Roles

An API key carries a role that bounds what it can do:

Role	Can do
VIEWER	Read configuration (pull, runtime reads, diff).
MEMBER	Everything VIEWER can, plus push schema and write secret values (set).

For runtime reads in production, prefer a VIEWER key — the app never needs write access. Use a MEMBER key for CI steps that run push or set.

Creating a key

Create keys from the project's settings in the portal dashboard. Optionally set an IP allowlist and an expiry for defense in depth.

Using a key

The CLI and SDK resolve the key in this order:

An explicit --api-key flag or apiKey option.
VAULTLIER_API_KEY in the environment.
The local credential cache from vaultlier init (dev only).

Terminal

# Production: set it in your platform's secret store
export VAULTLIER_API_KEY=vlt_live_...

# One-off CLI use
vaultlier pull --env=prod --api-key=vlt_live_...

# Persist to the local cache (development)
vaultlier config set apiKey=vlt_live_...

Account tokens vs API keys

These are two different credentials — don't confuse them:

Credential	Scope	Created by	Reads secrets?
`vlt_acct_…`	Account — list/create projects	vaultlier login	No
`vlt_live_…`	A single project	Portal dashboard	Yes (per role)

Account tokens from login can never read or write secrets. Secret access always requires a project API key.

Rotation & revocation

Revoke a key from the portal; revocation takes effect immediately.
To rotate, create a new key, deploy it via VAULTLIER_API_KEY, then revoke the old one.
Verify a key without exposing it using vaultlier config verify.

See Security for the full credential-handling guarantees.