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
- Create a free vault and add a secret (paste the setup key or upload the QR screenshot).
- Create an agent key under Agent keys, scoped to that secret. Copy it — it is shown once.
- 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.
curl -s https://otpilot.vibiz.app/api/v1/codes/shopify \
-H "Authorization: Bearer otp_live_YOUR_KEY"{
"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_inandnext_code; orpendingwhen approval is required.request_approval(account, reason)— emails the owner Approve / Deny links valid for 5 minutes.
Claude, Cursor & frameworks
Claude Code
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):
{
"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:
{
"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.
# 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.
// 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.
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.
# 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.
{
"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.
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.
// 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_key | No Authorization header. | Send Authorization: Bearer otp_live_… |
| 401 invalid_key / key_revoked | Unknown, mistyped or revoked key. | Create a new key in Agent keys. |
| 401 demo_expired | Demo tokens last 24 hours. | Make a new one on the home page or save to a vault. |
| 403 out_of_scope | The key is not allowed to read that account. | Tick the account on the key in the dashboard. |
| 403 ip_not_allowed | The key has an IP allowlist that excludes the caller. | Add the IP or call from an allowed one. |
| 403 approval_denied | A human denied the request. | Do not auto-retry; ask the owner. |
| 404 secret_not_found | No account with that name. | Call list_accounts / GET /api/v1/accounts. |
| 402 limit_fetches | The plan’s monthly fetches are used up. | Upgrade, or wait for the 1st (UTC). |
| 429 rate_limited | The key exceeded its per-minute limit. | Wait retry_after seconds or raise the 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.