Vault

Encrypted secret storage.

12 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`vault.status`

GET

Report whether the workspace cookie encryption key is properly configured. When configured=false, the dev fallback is being used and browser_sessions are encrypted with a deterministic key derived from a constant — readable by anyone with the code. Production deploys MUST set COOKIE_ENCRYPTION_KEY.

AI tool: vault_status
API: GET /api/invoke/vault.status

Input

No parameters.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

`vault.generate_key`

POST

Generate a fresh AES-256 key as base64 — for the user to copy into COOKIE_ENCRYPTION_KEY in their .env.local. The key is generated server-side and NEVER persisted; we hand it to the caller and forget it. Existing encrypted sessions become unreadable once the env var changes, so rotate carefully.

AI tool: vault_generate_key
API: POST /api/invoke/vault.generate_key

Input

No parameters.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

`vault.list_credentials`

GET

Unified view of everything stored at rest: encrypted browser sessions, Composio OAuth connections, and environment-secret presence audit. Returns metadata only — no decrypted cookies or token values.

AI tool: vault_list_credentials
API: GET /api/invoke/vault.list_credentials

Input

No parameters.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

`vault.activity`

GET

Recent credential-related events: session captures, test runs (active/expired verdicts), OAuth connect/disconnect. Derived from existing rows — no separate activity table. Useful as an audit trail.

AI tool: vault_activity
API: GET /api/invoke/vault.activity

Input

Field	Type	Required	Description
`limit`	integer	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}

`vault.secrets.list`

GET

List the manually-stored secrets the current actor can see — the ones they created plus the ones explicitly shared with them. Returns metadata only (field names + last-4 previews, owner, who it is shared with) — never the secret values. A secret is private to its creator by default.

AI tool: vault_secrets_list
API: GET /api/invoke/vault.secrets.list

Input

Field	Type	Required
`limit`	integer	—
`offset`	integer	—
`orderBy`	string	—
`orderDir`	"asc" \| "desc"	—
`q`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "orderBy": {
      "type": "string"
    },
    "orderDir": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "q": {
      "type": "string"
    }
  }
}

`vault.secrets.reveal`

POST

Decrypt and return one secret's field values. Access-gated: only the creator OR an actor the secret was shared with may reveal it. This is also how an AI agent USES a credential that was shared with it — the agent's own identity is the gate, so it can only read secrets explicitly shared with it. Handle the returned values carefully; they are sensitive.

AI tool: vault_secrets_reveal
API: POST /api/invoke/vault.secrets.reveal

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`vault.secrets.create`

POST · mutating

Store a new secret (API key, password, token, SSH key, note, …). Encrypted at rest. The secret is owned by — and visible only to — the actor that creates it until explicitly shared. fields is a map of named values, e.g. { value: "sk_live_…" } or { username: "…", password: "…" }.

AI tool: vault_secrets_create
API: POST /api/invoke/vault.secrets.create

Input

Field	Type	Required
`name`	string	yes
`description`	union	—
`kind`	string	—
`fields`	object	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "kind": {
      "type": "string"
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "name",
    "fields"
  ]
}

`vault.secrets.update`

PATCH · mutating

Rename, re-describe, re-classify, or re-key an existing secret. Creator only. Provide fields only when rotating the secret material; omit it to keep the stored value unchanged.

AI tool: vault_secrets_update
API: PATCH /api/invoke/vault.secrets.update

Input

Field	Type	Required	Description
`id`	string	yes
`patch`	object	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "patch": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "kind": {
          "type": "string"
        },
        "fields": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "id",
    "patch"
  ]
}

`vault.secrets.delete`

DELETE · mutating

Soft-delete a secret (and cascade its shares). Creator only.

AI tool: vault_secrets_delete
API: DELETE /api/invoke/vault.secrets.delete

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`vault.secrets.share`

POST · mutating

Grant another actor — a human teammate OR an AI agent in this workspace — access to a secret. After this, that actor can reveal/use the secret. Creator only. permission defaults to "use".

AI tool: vault_secrets_share
API: POST /api/invoke/vault.secrets.share

Input

Field	Type	Required
`id`	string	yes
`actorId`	string	yes
`permission`	"use" \| "manage"	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "actorId": {
      "type": "string",
      "minLength": 1
    },
    "permission": {
      "type": "string",
      "enum": [
        "use",
        "manage"
      ]
    }
  },
  "required": [
    "id",
    "actorId"
  ]
}

`vault.secrets.unshare`

POST · mutating

Revoke an actor's access to a secret. Creator only.

AI tool: vault_secrets_unshare
API: POST /api/invoke/vault.secrets.unshare

Input

Field	Type	Required	Description
`id`	string	yes
`actorId`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "actorId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id",
    "actorId"
  ]
}

`vault.audit`

GET

Read recent secret/credential access events from the audit log.

AI tool: vault_audit
API: GET /api/invoke/vault.audit

Input

No parameters.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": {}
}