Skip to main content

HashiCorp Vault

TokenTimer scans Vault KV v2 and PKI mounts over the REST API to discover secrets and certificates with expiration dates. No SDK or agent is required.

Vault URL format: https://vault.example.com:8200

The address must use http or https. TokenTimer Cloud trusts the public CA store. Unlike self-hosted (where you can set NODE_EXTRA_CA_CERTS on the API), Cloud does not let you attach a private Vault CA, so Vault must present a publicly trusted certificate.

Authenticate with a static token or AppRole (role ID and secret ID). The two modes are exclusive. Credentials are used for the scan only and are never stored for TokenTimer Cloud manual import. TokenTimer Cloud has no scheduled auto-sync for Vault (or any provider).

Optional Vault Enterprise or HCP namespace applies to both Token and AppRole (X-Vault-Namespace on every Vault call, including AppRole login).

Credential setup​

Option A: Vault token​

  1. Go to Vault UI → Access → Tokens → Create Token
  2. Attach a policy with at least read/list on the KV v2 and PKI mounts you scan (see Permissions)
  3. Set a TTL (recommended: 1-7 days for one-time use)
  4. Copy the token immediately (it will not be shown again)
  5. In TokenTimer, choose Token auth, paste the token, and set Namespace if your Vault uses one
  6. Revoke after use. The token is used for the scan only and never stored.

Option B: AppRole​

  1. Enable AppRole auth in Vault (default mount path approle, or note your custom path)
  2. Create a role whose token policies cover the mounts you scan
  3. Generate a role ID and secret ID for that role
  4. In TokenTimer, choose AppRole auth and enter:
    • Role ID and Secret ID (required)
    • Auth mount (optional; default approle; no leading or trailing slashes)
    • Namespace (optional; same field as Token auth; Vault Enterprise or HCP)
  5. A reusable SecretID (secret_id_num_uses=0) is practical when TokenTimer must authenticate more than once (listing mounts and scanning each use a login). HashiCorp prefers finite or single-use SecretIDs with external rotation when available. TokenTimer does not issue or rotate secret IDs.
  6. Credentials are used for the scan only and never stored.

Token and AppRole cannot be combined in one scan.

If AppRole is enabled at a path other than approle, set Auth mount to that path (no leading or trailing slashes). TokenTimer POSTs /v1/auth/<authMount>/login. Dot segments (. / ..) are rejected.

TokenTimer reads TTL from auth.lease_duration on the login response, not the top-level lease_duration (typically 0). When that TTL is greater than 0, it logs in again after about 80% of the lease, measured from when the login response is received. auth.lease_duration of exactly 0 keeps the client token for that scan only. A Vault 403 is treated as a permission or revocation failure, not as token expiry to retry. A failed AppRole refresh aborts the scan.

Load engines and Scan are separate API calls, so a manual import performs two AppRole logins.

TokenTimer does not revoke Vault tokens or secret IDs. Revoking the AppRole role or a secret ID stops future logins. An already-issued client token remains valid until its own TTL ends or you revoke it in Vault. Prefer short role and token TTLs.

A scan that cannot list mounts after a successful login is HTTP 403 with code: VAULT_PERMISSION_DENIED, not 502. A scan that can list a mount but cannot read some objects reports hasErrors / permissionDenied on that mount. The import UI shows a warning, not a green success badge.

Permissions required​

Minimum capabilities (example paths; adjust mount names to match your engines):

path "sys/mounts" {
  capabilities = ["read"]
}

path "secret/metadata/*" {
  capabilities = ["list"]
}

path "secret/data/*" {
  capabilities = ["read"]
}

path "pki/certs" {
  capabilities = ["list"]
}

path "pki/cert/*" {
  capabilities = ["read"]
}

KV v2 uses metadata/ and data/ prefixes. TokenTimer lists KV metadata and GETs KV v2 secret data (and PKI public certificate PEM) in memory to discover expiry and type. It does not persist secret values or private keys.

What is discovered​

  • KV v2 secrets: path, name, expiration (if present), auto-detected category/type
  • PKI certificates: serial, subject, issuer, expiration (notAfter)

PEM and base64 DER formats are supported. Smart heuristics auto-map types (for example certificates map to ssl_cert, API keys to api_key).

Scan options​

  • Filter rules: optional include/exclude rules (exact or regex, on name or description) applied to the scan preview and the import. See Filter rules.
  • Remove obsolete items: opt-in cleanup that deletes previously imported tokens no longer found at the source. See Obsolete-token cleanup.

Vault behind an allowlist​

If your Vault restricts inbound traffic by IP, allow TokenTimer Cloud's egress IP. See Egress IP allowlisting.