​
BYOK (Bring Your Own Key)

Agentik Vault uses a Bring Your Own Key model where you maintain full custody of your API keys for AI providers (OpenAI, Anthropic, etc.).
Your keys are encrypted at rest with AES-256-GCM and only decrypted inside your isolated instance.

​
Why BYOK?

Cost Control

You pay your AI provider directly. No markup or per-request fees from Agentik Vault.

Security

Keys never leave your control. They’re encrypted immediately upon upload and only decrypted in your instance.

Flexibility

Use any AI provider or service. Not locked into a specific vendor or pricing model.

Compliance

Meet regulatory requirements for key custody and data sovereignty.

​
Encryption Architecture

​
Encryption Details

  • Algorithm: AES-256-GCM (Galois/Counter Mode)
  • Key Size: 256 bits (32 bytes)
  • IV Size: 96 bits (12 bytes, randomly generated per encryption)
  • Auth Tag: 128 bits (16 bytes, for integrity verification)
  • Master Key: Stored in MASTER_KEY_ENCRYPTION env var (base64-encoded, 32 bytes)
The master encryption key must be 32 bytes (256 bits) and kept secret. If compromised, all stored API keys are at risk.

​
Upload API Keys

​
Via Dashboard

  1. Navigate to Instances and select your instance
  2. Click Configure Keys
  3. Enter key name and value:
    • Key name: OPENAI_API_KEY
    • Key value: sk-proj-...
  4. Click Add Key
  5. Repeat for other providers (Anthropic, etc.)
  6. Click Save — keys are encrypted immediately

​
Via API

curl -X POST https://api.agentik.dev/api/keys/store \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_7xKXtg2CW87",
    "keys": {
      "OPENAI_API_KEY": "sk-proj-...",
      "ANTHROPIC_API_KEY": "sk-ant-...",
      "CUSTOM_API_KEY": "your-custom-key"
    }
  }'
Response: 
{
  "success": true,
  "keys_stored": 3,
  "instance_id": "inst_7xKXtg2CW87"
}

​
Key Storage Format

Encrypted keys are stored in api_keys_encrypted table: 
CREATE TABLE api_keys_encrypted (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  instance_id VARCHAR(50) NOT NULL,
  key_name VARCHAR(100) NOT NULL,
  encrypted_value TEXT NOT NULL, -- JSON: {encrypted, iv, authTag}
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(instance_id, key_name)
);
Example encrypted value: 
{
  "encrypted": "a3f2b8c9d4e5...",
  "iv": "1a2b3c4d5e6f7a8b9c0d",
  "authTag": "9f8e7d6c5b4a3f2e1d0c"
}

​
Key Retrieval (Instance-Side)

Instances retrieve encrypted keys on startup: 
// Inside Docker instance startup
async function loadApiKeys() {
  const response = await fetch(`${BACKEND_URL}/api/keys/retrieve`, {
    headers: {
      "X-Instance-ID": process.env.INSTANCE_ID,
      "X-Instance-Secret": process.env.INSTANCE_SECRET, // Proof of instance identity
    },
  });
  
  const { keys } = await response.json();
  
  // Decrypt in-memory (never written to disk)
  for (const [name, encryptedBlob] of Object.entries(keys)) {
    const plaintext = decryptKey(encryptedBlob, process.env.ENCRYPTION_KEY);
    process.env[name] = plaintext; // Set as environment variable
  }
}

function decryptKey(blob: string, masterKey: string): string {
  const { encrypted, iv, authTag } = JSON.parse(blob);
  const decipher = crypto.createDecipheriv(
    'aes-256-gcm',
    Buffer.from(masterKey, 'base64'),
    Buffer.from(iv, 'hex')
  );
  
  decipher.setAuthTag(Buffer.from(authTag, 'hex'));
  
  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');
  
  return decrypted;
}
Keys are decrypted in-memory and never written to disk. They exist only in the instance’s RAM.

​
Key Rotation

Periodically rotate API keys for security:

​
Manual Rotation

  1. Generate new API key from provider (OpenAI, Anthropic)
  2. Update key in Agentik Vault:
curl -X PUT https://api.agentik.dev/api/keys/update \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_7xKXtg2CW87",
    "key_name": "OPENAI_API_KEY",
    "key_value": "sk-proj-NEW_KEY_HERE"
  }'
  1. Restart instance to load new key:
curl -X POST https://api.agentik.dev/api/instance/restart/inst_7xKXtg2CW87 \
  -H "Authorization: Bearer $TOKEN"

​
Automated Rotation (Enterprise)

Enterprise tier supports automated key rotation via webhooks: 
// Your rotation service
app.post('/webhook/rotate-keys', async (req, res) => {
  const { instance_id, provider } = req.body;
  
  // 1. Generate new key from provider API
  const newKey = await provider.generateApiKey();
  
  // 2. Update in Agentik Vault
  await agentikClient.updateKey(instance_id, `${provider}_API_KEY`, newKey);
  
  // 3. Revoke old key
  await provider.revokeApiKey(oldKey);
  
  res.json({ success: true });
});

​
Delete Keys

Remove API keys from an instance: 
curl -X DELETE https://api.agentik.dev/api/keys/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_7xKXtg2CW87",
    "key_names": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
  }'
Deleting keys will cause API calls in your instance to fail. Restart the instance after deletion.

​
Security Best Practices

Don’t reuse the same API key across multiple instances. This limits blast radius if one instance is compromised.
Rotate keys every 90 days or when team members leave. Automate rotation for critical workloads.
Track API usage at your provider’s dashboard. Unusual spikes may indicate key compromise.
Backend and frontend never log plaintext keys. Only log key name + last 4 chars for debugging.
Store MASTER_KEY_ENCRYPTION in secrets manager (AWS Secrets Manager, HashiCorp Vault). Never commit to Git.

​
Audit Logging

All key operations are logged for audit: 
SELECT * FROM audit_log 
WHERE action IN ('key_stored', 'key_updated', 'key_deleted', 'key_retrieved')
ORDER BY created_at DESC;
Example audit entry: 
{
  "timestamp": "2026-02-12T10:30:00Z",
  "user_id": "usr_abc123",
  "instance_id": "inst_7xKXtg2CW87",
  "action": "key_stored",
  "key_name": "OPENAI_API_KEY",
  "key_length": 51,
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0..."
}
Plaintext key values are never logged. Only metadata (name, length, timestamp) for compliance.

​
Compliance & Regulations

Agentik Vault’s BYOK model helps meet regulatory requirements:
  • GDPR: You control data processing via your own API keys
  • HIPAA: Encryption at rest + in transit (AES-256-GCM + TLS 1.3)
  • SOC 2: Audit logs for all key operations
  • PCI DSS: Key encryption meets Level 1 requirements

​
Troubleshooting

  • Check key was uploaded successfully (status 200)
  • Verify instance restarted after key update
  • Check instance logs for decryption errors
  • Ensure key format is correct (no extra spaces/newlines)
  • Verify MASTER_KEY_ENCRYPTION is set correctly (32 bytes base64)
  • Check backend logs for crypto errors
  • Ensure OpenSSL is available in backend environment
  • Verify instance ID and secret are correct
  • Check instance is in “running” state
  • Ensure backend can connect to database

​
Next Steps

API Reference

Explore the complete API documentation for key management endpoints