OTPilot

Docs

OTPilot docs

Two ways for an agent to get a code: one REST call, or the hosted MCP server. Both authenticate with an agent key and never return the seed.

Quickstart

  1. Create a free vault and add a secret (paste the setup key or upload the QR screenshot).
  2. Create an agent key under Agent keys, scoped to that secret. Copy it — it is shown once.
  3. Call the API or connect MCP as below. Your first code arrives in about 30 seconds.

No account yet? Paste a secret on the home page for a 24-hour demo token (otpd_…) that works with the same endpoints, using the account name demo.

REST API

Base URL https://otpilot.vibiz.app. Header Authorization: Bearer otp_live_… (or X-API-Key).

GET /api/v1/codes/{account}

Returns the current code. Optional ?reason= (or header X-OTPilot-Reason) is stored in the audit log and shown to approvers.

request
curl -s https://otpilot.vibiz.app/api/v1/codes/shopify \
  -H "Authorization: Bearer otp_live_YOUR_KEY"
200 response
{
  "status": "issued",
  "account": "shopify",
  "code": "482913",
  "next_code": "105227",
  "expires_in": 17,
  "period": 30,
  "digits": 6,
  "approval": "auto"
}

If the account requires approval you get 202 with { "status": "pending", "approval_id", "expires_at", "poll_after_seconds": 5 }. Poll the same URL; once approved it returns 200 with the code (one code per approval).

GET /api/v1/accounts

Lists the accounts this key may read: name, issuer, label, digits, period, whether approval is required. Never seeds.

POST /api/v1/approvals

Body { "account": "aws-prod", "reason": "rotate IAM keys" }. Asks the owner to approve before you poll for the code.

MCP server

Streamable HTTP at https://otpilot.vibiz.app/mcp, authenticated with the same Authorization: Bearer header. Tools:

  • list_accounts() — the accounts this key can read.
  • get_code(account, reason?) — current code, expires_in and next_code; or pending when approval is required.
  • request_approval(account, reason) — emails the owner Approve / Deny links valid for 5 minutes.

Claude, Cursor & frameworks

Claude Code

shell
claude mcp add --transport http otpilot https://otpilot.vibiz.app/mcp \
  --header "Authorization: Bearer otp_live_YOUR_KEY"

Cursor

Add to .cursor/mcp.json (or ~/.cursor/mcp.json):

json
{
  "mcpServers": {
    "otpilot": {
      "url": "https://otpilot.vibiz.app/mcp",
      "headers": {
        "Authorization": "Bearer otp_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop connects to remote servers through mcp-remote. Add to claude_desktop_config.json:

json
{
  "mcpServers": {
    "otpilot": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://otpilot.vibiz.app/mcp",
        "--header",
        "Authorization:${OTPILOT_AUTH}"
      ],
      "env": {
        "OTPILOT_AUTH": "Bearer otp_live_YOUR_KEY"
      }
    }
  }
}

Browser Use

Give the Browser Use agent a custom action that fetches the current code when a login asks for it. Full Browser Use guide.

python
# pip install browser-use httpx
import os, httpx
from browser_use import Agent, Tools

tools = Tools()

@tools.action("Get the current 2FA authenticator code for Shopify")
def get_2fa_code(account: str = "shopify") -> str:
    r = httpx.get(
        f"https://otpilot.vibiz.app/api/v1/codes/{account}",
        headers={"Authorization": f"Bearer {os.environ['OTPILOT_KEY']}"},
        params={"reason": "Browser Use login"},
    )
    r.raise_for_status()
    data = r.json()
    if data["status"] == "pending":
        return "Approval pending - wait 5 seconds and call get_2fa_code again"
    return data["code"]

agent = Agent(
    task="Log into Shopify. When asked for an authenticator code, call get_2fa_code.",
    llm=llm,  # your model
    tools=tools,
)
await agent.run()

Stagehand

Fetch the code right before Stagehand fills the 2FA field, so it is always fresh. Full Stagehand guide.

typescript
// npm i @browserbasehq/stagehand
async function otp(account = "shopify") {
  const r = await fetch(`https://otpilot.vibiz.app/api/v1/codes/${account}?reason=stagehand-login`, {
    headers: { Authorization: `Bearer ${process.env.OTPILOT_KEY}` },
  });
  const data = await r.json();
  if (!r.ok) throw new Error(`${data.error.message} Fix: ${data.error.fix}`);
  if (data.status === "pending") { await new Promise((s) => setTimeout(s, 5000)); return otp(account); }
  return data.code as string;
}

await page.act("log into Shopify with the saved email and password");
const code = await otp();
await page.act(`type ${code} into the authenticator code field and submit`);

Playwright

A tiny helper for Playwright scripts and tests that log into real accounts. Full Playwright guide.

typescript
import { test } from "@playwright/test";

async function otp(account = "shopify") {
  const r = await fetch(`https://otpilot.vibiz.app/api/v1/codes/${account}`, {
    headers: { Authorization: `Bearer ${process.env.OTPILOT_KEY}` },
  });
  const data = await r.json();
  if (!r.ok) throw new Error(`${data.error.message} Fix: ${data.error.fix}`);
  // If the code is about to roll over, use the next one.
  return data.expires_in < 4 ? data.next_code : data.code;
}

test("log into Shopify", async ({ page }) => {
  // ...fill email + password...
  await page.getByLabel(/authentication code|verification code|2fa/i).fill(await otp());
  await page.keyboard.press("Enter");
});

OpenAI Agents SDK

Attach OTPilot as a streamable-HTTP MCP server to any agent built with the OpenAI Agents SDK. Full OpenAI Agents SDK guide.

python
# pip install openai-agents
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="otpilot",
    params={
        "url": "https://otpilot.vibiz.app/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['OTPILOT_KEY']}"},
    },
) as otpilot:
    agent = Agent(
        name="Ops agent",
        instructions="When a Shopify login asks for a 2FA code, call get_code(account='shopify').",
        mcp_servers=[otpilot],
    )
    await Runner.run(agent, "Log into Shopify and download last month's invoices")

n8n

Use an HTTP Request node to fetch the code mid-workflow and pass it to your browser or API step. Full n8n guide.

json
{
  "name": "OTPilot: get 2FA code",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "GET",
    "url": "https://otpilot.vibiz.app/api/v1/codes/shopify",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "options": {}
  },
  "credentials": {
    "httpHeaderAuth": { "name": "Authorization", "value": "Bearer otp_live_YOUR_KEY" }
  }
}
// Output: {{ $json.code }} — use it in the next node.

Make

Add an HTTP "Make a request" module before the step that needs the code. Full Make guide.

text
Module: HTTP › Make a request
URL:     https://otpilot.vibiz.app/api/v1/codes/shopify
Method:  GET
Headers: Authorization = Bearer otp_live_YOUR_KEY
Parse response: Yes

Map {{data.code}} into the next module.
If {{data.status}} = "pending", add a 5-second Sleep and repeat (approval mode).

Puppeteer

Fetch the code and type it into the 2FA input in your Puppeteer script. Full Puppeteer guide.

javascript
// Log into Shopify with Puppeteer + OTPilot
const res = await fetch("https://otpilot.vibiz.app/api/v1/codes/shopify", {
  headers: { Authorization: `Bearer ${process.env.OTPILOT_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.message} Fix: ${data.error.fix}`);

await page.type('input[autocomplete="one-time-code"], input[name*="otp" i], input[name*="code" i]', data.code);
await page.keyboard.press("Enter");

Human approval

Turn on “Require human approval” for a secret (Pro and Team). The first get_code creates a request and emails the vault owner a link to a mobile page with Approve and Deny. The agent polls every 5 seconds; after Approve, exactly one code is released to that key within 5 minutes. Deny returns 403 approval_denied. Requests expire after 5 minutes.

Errors

Every error is JSON: { "error": { "code", "message", "why", "fix" } } — what failed, why, and how to fix it.

401 missing_keyNo Authorization header.
401 invalid_key / key_revokedUnknown, mistyped or revoked key.
401 demo_expiredDemo tokens last 24 hours.
403 out_of_scopeThe key is not allowed to read that account.
403 ip_not_allowedThe key has an IP allowlist that excludes the caller.
403 approval_deniedA human denied the request.
404 secret_not_foundNo account with that name.
402 limit_fetchesThe plan’s monthly fetches are used up.
429 rate_limitedThe key exceeded its per-minute limit.

Limits

  • Per key: 10 codes per minute by default (1–120, set per key).
  • Per month: Free 300, Pro 20,000, Team 100,000 issued codes.
  • Approval emails share the service’s daily email budget; in the rare case it is reached the request stays pending in the dashboard.