Environments & API Keys

VeriProof provides two isolated environments: sandbox for development and testing, and production for live workloads. API keys are scoped to a single environment — a sandbox key will never write to production data, and vice versa.

Environments

Switching between environments

The SDK uses the same ingest endpoint for both environments. The environment is determined by your API key:

• Sandbox keys have a _sandbox_ component in the key and automatically route through the sandbox partition.
• An additional X-Veriproof-Sandbox: true header is required when using the REST API directly. The SDK sets this automatically for sandbox keys.

from veriproof_sdk import VeriproofClientOptions, configure_veriproof
 
# Sandbox (development)
configure_veriproof(
    VeriproofClientOptions(
        api_key=os.environ["VERIPROOF_SANDBOX_KEY"],   # sandbox-scoped key
        application_id="loan-review",
    ),
    service_name="loan-review",
    set_global=True,
)
 
# Production — identical code, different key
configure_veriproof(
    VeriproofClientOptions(
        api_key=os.environ["VERIPROOF_API_KEY"],       # production-scoped key
        application_id="loan-review",
    ),
    service_name="loan-review",
    set_global=True,
)

API key format

VeriProof API keys follow a compound format that encodes the customer account, Azure backend component, and a secondary secret component:

vp_cust_{customer-slug}.{azure-component}.{secondary-token}
     │         │               │                  │
     │         │               │                  └─ Per-key secret
     │         │               └─ Azure Key Vault component reference
     │         └─ Your customer account slug
     └─ Prefix: identifies this as a VeriProof customer key

Example (illustrative — not a real key):

vp_cust_acme.akv7f4a2b.3xQr9pLmN8vT

This format means:

• Keys are always recognizable in logs and code review (prefix vp_cust_)
• The Azure component reference allows the backend to locate the corresponding Key Vault secret without storing the key itself in the database
• Rotating a key does not require changing the customer slug component

Key scopes

Each key is scoped at creation time and cannot be upgraded to a wider scope after the fact.

Most integrations only need ingest:write. Keys with ingest:read are used for enterprise integrations that pull verification proofs programmatically.

Managing API keys

Generate a new key

1. In the Customer Portal, open Settings, then select Security.
2. In the Customer Keys panel, click Request New Key.
3. Complete the request flow with the required scope and environment.
4. Capture the key when the request is executed — plaintext is only shown once.

Rotate a key

Rotating a key does not cause downtime if you follow this sequence:

1. Generate a new key with the same scope.
2. Update your application’s secret configuration to use the new key.
3. Deploy the updated configuration.
4. Verify traces are arriving in the portal using the new key.
5. Return to Settings → Security and submit a revoke request for the old key.

Revoke a key

From Settings → Security, use the Customer Keys panel to submit a revoke request for the active key. Once executed, any in-flight requests using the revoked key will receive a 401 Unauthorized response.

Storing keys securely

Never:

• Commit API keys to source control (use .gitignore for .env files)
• Log API keys in application output or error messages
• Include keys in client-side JavaScript or mobile app bundles

Do:

• Store in your platform’s secret manager (Azure Key Vault, AWS Secrets Manager, Kubernetes Secrets, HashiCorp Vault)
• Pass keys to the SDK via environment variable (VERIPROOF_API_KEY) or a Callable key provider for dynamic rotation
• Audit key access in your secret manager’s activity log

Dynamic key rotation with a provider function

from veriproof_sdk import VeriproofClientOptions, configure_veriproof
from azure.keyvault.secrets import SecretClient
 
def get_api_key() -> str:
    # Called on each SDK export — returns the current key from Key Vault
    return secret_client.get_secret("veriproof-api-key").value
 
configure_veriproof(
    VeriproofClientOptions(
        api_key_provider=get_api_key,         # Callable — keys never cached in memory
        application_id="loan-review",
    ),
    service_name="loan-review",
    set_global=True,
)

Enterprise: Custom ingest endpoint

Enterprise Federated deployments host their own ingest endpoint inside a customer-owned Azure tenant. Override the endpoint via environment variable or SDK option:

VERIPROOF_ENDPOINT=https://ingest.ai.yourdomain.com

VeriproofClientOptions(
    api_key=os.environ["VERIPROOF_API_KEY"],
    application_id="loan-review",
    endpoint="https://ingest.ai.yourdomain.com",
)

Next steps

• Sandbox Demo — explore VeriProof with pre-loaded demo data
• API Authentication — compound key model and security deep-dive
• SDK Reference — Python — full VeriproofClientOptions reference