Token Vault

The Token Vault allows AI Agents to securely store and retrieve third-party API keys (like OpenAI, Stripe, or any other service) at runtime, without exposing them in code or prompts.

Why Token Vault?

Without a vault, developers often:

• Hardcode API keys (security risk)
• Pass keys through LLM prompts (leak risk)
• Store in environment variables (not per-tenant)

Token Vault solves this by:

• Encrypting at rest with AES-256-GCM
• Per-organization isolation (each org has unique encryption)
• Full audit trail of every access
• Optional TTL for auto-expiring secrets

Quick Start

curl -X POST https://id.optare.one/vault/secrets \
  -H "Authorization: Bearer YOUR_M2M_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai_api_key",
    "value": "sk-abc123..."
  }'

const response = await fetch('/vault/secrets/openai_api_key', {
  headers: { Authorization: `Bearer ${m2mToken}` }
});
 
const { value } = await response.json();
 
// Use it
const openai = new OpenAI({ apiKey: value });

API Reference

Create/Update Secret

POST /vault/secrets

Request Body:

{
  "name": "stripe_secret_key",
  "value": "sk_live_...",
  "scope": ["payments"],
  "expiresAt": "2025-12-31T23:59:59Z"
}

Response:

{
  "success": true,
  "action": "created"
}

Retrieve Secret

GET /vault/secrets/:name

Response:

{
  "name": "stripe_secret_key",
  "value": "sk_live_...",
  "scope": ["payments"],
  "expiresAt": "2025-12-31T23:59:59Z"
}

List Secrets

GET /vault/secrets

Response:

{
  "secrets": [
    {
      "name": "openai_api_key",
      "scope": [],
      "expiresAt": null,
      "createdAt": "2025-12-23T00:00:00Z"
    }
  ]
}

Delete Secret

DELETE /vault/secrets/:name

Response:

{
  "success": true,
  "action": "deleted"
}

Ownership Models

Token Vault supports two ownership models:

When creating a secret:

• If authenticated with M2M token (client_credentials): Secret is App-Level
• If authenticated with User token: Secret is User-Level

Security

Encryption

• Algorithm: AES-256-GCM (NIST approved)
• Key Derivation: HMAC-SHA256 with per-organization salt
• Storage: Base64-encoded ciphertext only

Access Control

• Secrets are scoped to the organization in the token
• App-level secrets require matching client_id
• User-level secrets require matching user_id

Audit Logging

Every vault operation is logged:

• vault.secret.created
• vault.secret.retrieved
• vault.secret.updated
• vault.secret.deleted

Portal UI

Organization admins can manage secrets visually at:

/portal/vault

Features:

• Add new secrets with encryption
• Assign secrets to specific OAuth Clients
• Delete secrets with confirmation
• View creation dates and scopes

Environment Setup

Add the master encryption key to your environment:

# Generate a secure 32-byte key
openssl rand -hex 32
 
# Add to .env
VAULT_MASTER_KEY=your_64_character_hex_string