API-based Integration Quick Start

BotVault has two integrations. This section covers the API-based integration, where a bot calls /api/v1/credentials over HTTP with a bearer token. The other integration is MCP-based (npx @botvault/cli install) and is documented in packages/cli/README.md.

Use the API-based integration whenever a bot can't use MCP — most commonly because the bot runs somewhere other than the operator's own computer (LangChain on AWS Lambda, cloud-hosted OpenClaw, GitHub Actions, n8n, Zapier, hosted agents). The MCP-based path requires a passkey paired to physical hardware, which can't move to a cloud VM by design. Both integrations talk to the same vault, with the same per-bot permissions and audit log.

1. Create the bot and generate a token

In the dashboard at https://mybotvault.com:

1. Sign in (signup is free).
2. Bots → Create bot. Name it after where it will run (e.g. langchain-prod, openclaw-cloud).
3. Bots → [your bot] → Permissions. Select the credentials this bot is allowed to read. Grant only what it needs.
4. Bots → [your bot] → Tokens → Generate token. Pick a TTL (30d / 90d / 1y / never). Copy the token now — it's shown once.

The token is a JWT. The token alone authorizes the bot — anyone with the token can read the credentials it has permission to access, so treat it like a password.

2. Configure the agent

Set the token as an environment variable on the agent. Never commit it to source control.

# AWS Lambda / Fargate / ECS — task definition env vars
BOTVAULT_TOKEN=eyJhbGciOi...

# GitHub Actions — repo secrets
BOTVAULT_TOKEN=eyJhbGciOi...

# n8n / Zapier — credential / connection setting
BOTVAULT_TOKEN=eyJhbGciOi...

# Cloud-hosted OpenClaw — instance environment
BOTVAULT_TOKEN=eyJhbGciOi...

3. Call the API

Two endpoints. Both are rate limited to 60 req/min per token.

List credentials (metadata only — no secret values)

curl -H "Authorization: Bearer $BOTVAULT_TOKEN" \
  https://mybotvault.com/api/v1/credentials

{
  "credentials": [
    { "id": "9639b427-...", "label": "OpenAI Key", "type": "API Key", "expires_at": "2026-08-02 23:59:59" },
    { "id": "62d3c8a1-...", "label": "Vercel Token", "type": "Token", "expires_at": null }
  ]
}

Fetch a credential's value

curl -H "Authorization: Bearer $BOTVAULT_TOKEN" \
  https://mybotvault.com/api/v1/credentials/9639b427-...

{
  "id": "9639b427-...",
  "label": "OpenAI Key",
  "type": "API Key",
  "value": "sk-..."
}

4. Code examples

Node.js / TypeScript:

const token = process.env.BOTVAULT_TOKEN!;

async function getCredential(id: string): Promise<string> {
  const res = await fetch(`https://mybotvault.com/api/v1/credentials/${id}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!res.ok) throw new Error(`BotVault ${res.status}: ${await res.text()}`);
  const { value } = await res.json();
  return value;
}

const openaiKey = await getCredential('9639b427-...');

Python (LangChain / AutoGPT / custom):

import os, requests

BOTVAULT_TOKEN = os.environ["BOTVAULT_TOKEN"]
BASE = "https://mybotvault.com/api/v1"

def get_credential(cred_id: str) -> str:
    r = requests.get(
        f"{BASE}/credentials/{cred_id}",
        headers={"Authorization": f"Bearer {BOTVAULT_TOKEN}"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["value"]

openai_key = get_credential("9639b427-...")

Cloud-hosted OpenClaw — system prompt template:

A cloud-hosted OpenClaw can't use the MCP-based integration (the passkey is tied to its operator's physical device, not the cloud VM). Give it the API-based integration via its system prompt:

You have access to BotVault, a credential vault.

To list credentials: GET https://mybotvault.com/api/v1/credentials
To fetch a value:    GET https://mybotvault.com/api/v1/credentials/<id>

Both require the header `Authorization: Bearer <BOTVAULT_TOKEN>`,
where BOTVAULT_TOKEN is provided to you in the environment.

Rules:
- Always list credentials first to discover what you have access to.
- Never log credential values, never echo them to the user.
- Fetch a value only at the moment of use; don't cache long-term.
- If a request returns 401, the token is invalid or expired — stop the
  task and tell the operator to issue a new token in the BotVault
  dashboard.
- If a request returns 403 for an ID you saw in `list`, your permissions
  changed — re-list before reporting it as missing.
- If a request returns 429, wait 60 seconds and retry.

5. What to tell the AI

Your agent needs to know how and when to call the BotVault API. The cleanest way: paste BotVault's skill text into the agent's system prompt. The skill is a short set of rules the agent reads before doing anything that involves credentials.

The skill tells the agent to:

• List credentials before assuming what's available — re-list at the start of every task that touches credentials, since permissions can change.
• Check BotVault first before asking the operator to generate or paste a credential.
• Fetch a credential value only at the moment of use; never cache long-term.
• Never log credential values, echo them to the operator, or include them in conversation context.
• Handle 401 / 403 / 429 / expired responses correctly (stop the task, surface the right operator action).
• Use Authorization: Bearer <BOTVAULT_TOKEN> on every request, where BOTVAULT_TOKEN is the env var you set in step 2.

Copy the BotVault skill below and paste it into your agent's system prompt — once at agent setup time, never per-request. The bot token is not in the text; you've already set BOTVAULT_TOKEN as an env var separately.

The skill text is also visible below the page content.

6. Permissions, rotation, security

• Per-credential permissions are enforced server-side. The bot only sees credentials its grants include.
• Tokens are revocable. Dashboard → Bots → [your bot] → Tokens → Revoke. Effective immediately.
• Rotate tokens regularly. Generate a new one, deploy it, then revoke the old one.
• Audit log records every read. Dashboard → Settings → Audit Log → filter by bot.
• Webhooks can fire when permissions or credentials change — see POST /api/v1/webhooks below.

If the agent runs in an environment with a secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, etc.), store BOTVAULT_TOKEN there and fetch it on cold start — better than a plaintext env var.