Security and trust

BehalfID does not magically control an agent by itself. The app or provider must call BehalfID before acting. If the action is denied, the integration should fail closed and not execute the action.

Fail closed means the agent throws on denial and the code that would execute the action never runs. The opposite — fail open — would let the agent proceed if the check fails or is unavailable. BehalfID's recommended enforcement pattern is always fail closed.

const result = await behalf.verify({
  agentId,
  action: "purchase",
  vendor: "coachella.com",
  amount: 742
});

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

// Only execute the action after this point.

Enforcement only works when the integration calls BehalfID before acting and respects the response. See the live sandbox for a browser-based demonstration.

Manual mode is for testing with existing agents — Ollie, ChatGPT, Claude, Zapier, Make, or others — without requiring the provider to integrate BehalfID.

A passport link shares active permission scopes in a structured format any AI can read. An agent memory block is a text snippet that can be pasted into a system prompt. Neither constitutes enforcement — they are advisory inputs.

Because BehalfID cannot intercept requests to third-party providers, manual mode relies entirely on the external model reading and respecting the listed permissions. A model that ignores instructions or hallucinates permission grants cannot be stopped by BehalfID in manual mode.

BehalfID stores the following credentials:

• API keys (bhf_sk_…) — stored as SHA-256 hashes. A key is shown to you exactly once at creation time. If lost, it cannot be recovered; rotate to get a new one.
• Passport tokens (bhf_pt_…) — stored as SHA-256 hashes. Anyone who obtains a passport token can read the active permission scopes for that agent. Treat passport tokens as secrets.
• Webhook signing secrets — stored as SHA-256 hashes. Verify incoming webhook signatures with verifyWebhookSignature before processing.
• Developer passwords — hashed with scrypt. Plaintext passwords are never stored.

BehalfID never transmits credentials in plaintext in API responses. Keys are shown once, then discarded.

A public passport URL (behalfid.com/passport/[agentId]) is designed to be shareable. It shows only what an AI assistant needs to know about its current permission scope.

The passport page does not expose:

• API keys or key hashes
• Webhook secrets or signing keys
• Account owner email or personal data
• Internal agent IDs (beyond what is visible in the URL)

Every verification request produces an immutable audit log entry. Entries include:

• Request ID (stable, for cross-system correlation)
• Agent ID and action
• Decision (allowed / denied / approval-required)
• Risk level and denial reason
• Timestamp

Logs are scoped to your account and visible in the developer portal. Verification logs are retained for 90 days. You can delete individual log entries or all logs from the logs page.

BehalfID signs every webhook payload with HMAC-SHA256. The signature is in the X-BehalfID-Signature header.

Always verify signatures before processing events. The SDK exports a verifyWebhookSignature(secret, rawBody, signature) helper. Webhook delivery records are retained for 30 days.