API Keys

Veriproof uses API keys to authenticate requests from your applications and backend services. In the current Customer Portal UI, key management is handled from the Customer Keys panel in Settings → Account → Security.

API key management requires the CustomerAdmin role.

Key Prefixes

Prefix	Environment	Use
`vp_live_`	Production	Session ingest, blockchain anchoring
`vp_test_`	Sandbox	Testing and CI pipelines (no real anchoring)

Keys are only shown once at the time of creation. Copy and store them securely in a secrets manager (e.g. Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) immediately.

Never commit API keys to source control. Never log them in application output. If a key is accidentally exposed, revoke it immediately.

Issuing a New Key

Open Customer Keys

In the Customer Portal, open Settings, select Account → Security, and use the Customer Keys panel.

Submit a key request

Select Request New Key. Complete the request with the target application and environment:

Ingest key (vp_live_* / vp_test_*) — authorizes session ingest SDK calls
Secondary key — additional rotation-ready key you can swap to with zero downtime

Capture the key

The full key value is displayed once after the request is executed. Copy it to your secrets store before closing the dialog. The portal only shows masked metadata afterwards.

Add to your application

Set the key as the VERIPROOF_API_KEY environment variable (or the equivalent configuration in your secrets manager). The SDK picks it up automatically:


# .env or container environment
VERIPROOF_API_KEY=vp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key Rotation

Rotating a key means requesting a new key and invalidating the old one. The current portal uses a request-driven workflow:

Request a replacement key

While your current key is still active, use Request New Key for the same application so you can cut over without downtime.

Deploy the new key to your application

Update your secret store and redeploy (or hot-reload) your application to use the new key.

Revoke the old key

Once you have confirmed that traffic is flowing through the new key, return to Settings → Account → Security and submit a revoke request for the original key.

The old key is permanently invalidated. Any requests still using it will receive 401 Unauthorized.

Revoking a Key

To invalidate a key:

Open Settings → Account → Security.
In Customer Keys, locate the active key.
Submit a revoke request for that key.

Revocation takes effect when the request is executed. Generate a replacement key before revoking if traffic continuity is required.

Viewing Key Metadata

The Customer Keys panel shows all keys across your tenant with:

Column	Description
Prefix	Masked key prefix (e.g. `vp_live_abc1...`)
Application	The application this key is scoped to
Type	Primary ingest / secondary / management
Created	Creation timestamp
Created by	Admin who issued the key
Last used	Approximate last-use timestamp (hourly buckets)
Status	Active / Revoked

API Reference

Keys are managed via the customer-keys endpoint:


GET    /v1/customer-keys                      # List all key metadata (masked)
POST   /v1/customer-keys/issue                # Issue a new secondary key
DELETE /v1/customer-keys/{keyId}              # Revoke a key by ID
GET    /v1/customer-keys/requests             # List key management requests
POST   /v1/customer-keys/requests/{action}    # Submit a key request (rotate-tenant-key, etc.)

Direct self-service operations

POST /v1/customer-keys/issue and DELETE /v1/customer-keys/{keyId} execute immediately without a staff approval step. The key is available for immediate use or is invalidated immediately on revocation.

Staff-executed requests

Some operations (such as rotating the master tenant encryption key) require staff execution and go through a request/approval workflow. Use POST /v1/customer-keys/requests/{action} to submit these. Check the status at GET /v1/customer-keys/requests/{id}.

Key Security Best Practices

Use environment variables or a secrets manager — never hardcode keys in source files.
Scope keys to the minimum required access — use application-scoped keys, not tenant-wide keys, when possible.
Rotate proactively — schedule key rotations every 90 days as a security hygiene measure, not just in response to suspected compromise.
Monitor Last Used — keys that have not been used for 30+ days may belong to decommissioned systems and should be revoked.
Use sandbox keys in CI — vp_test_* keys never anchor to the real blockchain and are safe to use in automated pipelines with appropriately restricted permissions.