Documentation

Quickstart

Create an agent, add one permission, verify before execution, and prove both allowed and denied actions in about five minutes.

The five-minute model

BehalfID sits between the AI agent and the tool it wants to run. Your code asks BehalfID first. If the decision is not allowed, the executor does not run.

1. Create an agent. Use /dashboard/onboarding or behalf agents create. Store the one-time bhf_sk_... API key as BEHALFID_API_KEY.
2. Create a permission. Start with one clear rule — for a coding agent: deploy on vercel.com with requiresApproval: true for production.
3. Install the SDK. Add the published Node SDK to the app that owns the tool execution.
4. Call verify before the action. The SDK requires agentId, action, and the API key.
5. Fail closed. Throw or return before the executor. Never run the tool when decision.allowed is false.

npm install @behalfid/sdk

Copy-paste executor pattern

import { BehalfID } from "@behalfid/sdk";

const behalf = new BehalfID({
  apiKey: process.env.BEHALFID_API_KEY!,
});

const agentId = process.env.BEHALFID_AGENT_ID!;

async function deployToProduction(vendor: string) {
  const decision = await behalf.verify({
    agentId,
    action: "deploy_production",
    vendor,
  });

  if (!decision.allowed) {
    throw new Error(`Blocked by BehalfID: ${decision.reason}`);
  }

  return runDeploy({ vendor, env: "production" });
}

Allowed request

{
  "requestId": "req_xxx",
  "allowed": true,
  "reason": "Action allowed by active permission.",
  "risk": "low"
}

Approval-required request

{
  "requestId": "req_xxx",
  "allowed": false,
  "reason": "Permission requires approval before execution.",
  "risk": "medium"
}

Denied request

{
  "requestId": "req_xxx",
  "allowed": false,
  "reason": "Amount exceeds maxAmount constraint.",
  "risk": "high"
}