Vault API

Manage encrypted secrets programmatically.

List Secrets

GET /api/agents/:name/vault

Response

{
  "secrets": [
    {
      "key": "OPENAI_API_KEY",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "key": "TELEGRAM_TOKEN",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ]
}

::: note Secret values are never returned in list endpoints. :::

Get Secret

GET /api/agents/:name/vault/:key

Response

{
  "key": "OPENAI_API_KEY",
  "value": "sk-xxxxxxxxxxxx",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Store Secret

POST /api/agents/:name/vault

Request

{
  "key": "DATABASE_PASSWORD",
  "value": "supersecret123"
}

Response

{
  "success": true,
  "key": "DATABASE_PASSWORD",
  "created_at": "2024-01-15T12:00:00Z"
}

Update Secret

PUT /api/agents/:name/vault/:key

Request

{
  "value": "newsecret456"
}

Response

{
  "success": true,
  "key": "DATABASE_PASSWORD",
  "updated_at": "2024-01-15T12:30:00Z"
}

Delete Secret

DELETE /api/agents/:name/vault/:key

Response

{
  "success": true,
  "message": "Secret 'OLD_KEY' deleted"
}

Check Secret Exists

HEAD /api/agents/:name/vault/:key

Response

• 200 OK - Secret exists
• 404 Not Found - Secret does not exist

Batch Operations

Store Multiple Secrets

POST /api/agents/:name/vault/batch

Request

{
  "secrets": {
    "API_KEY_1": "value1",
    "API_KEY_2": "value2",
    "API_KEY_3": "value3"
  }
}

Response

{
  "success": true,
  "created": 3,
  "keys": ["API_KEY_1", "API_KEY_2", "API_KEY_3"]
}

Delete Multiple Secrets

DELETE /api/agents/:name/vault/batch

Request

{
  "keys": ["OLD_KEY_1", "OLD_KEY_2"]
}

Export/Import

Export Secrets (Metadata Only)

GET /api/agents/:name/vault/export

Response

{
  "agent": "default",
  "exported_at": "2024-01-15T12:00:00Z",
  "secrets": [
    {"key": "OPENAI_API_KEY"},
    {"key": "TELEGRAM_TOKEN"}
  ]
}

::: note Full secret values are never exported via API for security. :::

Predefined Secret Keys

These secrets have special meaning:

Key	Purpose
openai_api_key	OpenAI API key
google_api_key	Google API key
xai_api_key	Z.Ai (Grok) API key
llm_model	Default LLM model
llm_provider	Active LLM provider
llm_temperature	Temperature setting
telegram_token	Telegram bot token
discord_token	Discord bot token
slack_bot_token	Slack bot token
slack_app_token	Slack app token
gateway_host	API bind address
gateway_port	API port
web_ui_port	Web dashboard port
whisper_model	Whisper model for voice
embedding_model	Embedding model for LTM
stm_window_size	STM context window
webhook_secret	Webhook authentication

Security Notes

1. Transport - Always use HTTPS in production
2. Access - Vault requires agent-level access
3. Audit - All vault operations are logged
4. Encryption - Secrets are encrypted at rest
5. Memory - Values cleared from memory after use

Error Responses

Secret Not Found

{
  "success": false,
  "error": {
    "code": "SECRET_NOT_FOUND",
    "message": "Secret 'UNKNOWN_KEY' not found"
  }
}

Invalid Key Name

{
  "success": false,
  "error": {
    "code": "INVALID_KEY",
    "message": "Key must be alphanumeric with underscores"
  }
}