Введение

Основные понятия

Панель управления

Интеграция

Идентификаторы агентов

Авторизация

Справочник API

Эксплуатация

Для AI-агентов

Машиночитаемая документация доступна в llms.txt и docs.md.

/llms.txt /llms-full.txt /docs.md

Документация разработчика

Проверяйте AI-агентов до предоставления доступа к API

Интегрируйте криптографическую проверку, политики доверия, ключи подписи, авторизацию MCP и аналитику.

Введение

Обзор AgentBouncer

Проверяйте подписанные запросы ИИ-агентов и применяйте политики доступа конкретного проекта.

AgentBouncer проверяет подписи HTTP-сообщений, отправленные ИИ-агентами, определяет открытый ключ подписанта, оценивает политику вашего проекта и возвращает итоговое решение о доступе.

Самое важное правило интеграции

Используйте allowed как итоговое решение об авторизации. Поле verified сообщает результат криптографической проверки, а allowed — фактическое решение политики проекта.

verified	allowed	Значение
true	true	Подпись действительна, и запрос разрешён.
true	false	Подпись действительна, но политика проекта запретила доступ.
false	true	Запрос не прошёл проверку, но был разрешён режимом MONITOR_ONLY или другой разрешающей настройкой.
false	false	Запрос не прошёл проверку, и доступ был запрещён.

Проверяйте подписи HTTP-сообщений по стандарту RFC 9421.
Получайте открытые ключи провайдеров и ключи, принадлежащие проекту.
Применяйте уровни доверия, оценки доверия, действия, инструменты и пользовательские правила.
Защищайте инструменты MCP, API, операции оформления заказа и автономные рабочие процессы.
Сохраняйте события проверки для аналитики и расследования инцидентов.

Введение

Быстрый старт

Создайте проект, скопируйте API-ключ и защитите конечную точку.

1
Создайте проект
Откройте панель управления AgentBouncer, создайте проект и укажите origin или хост сервиса, который вы хотите защитить.
2
Начните с режима мониторинга
На первом этапе интеграции используйте MONITOR_ONLY. Запросы продолжат выполняться, а AgentBouncer будет фиксировать, какие из них были бы заблокированы.
3
Скопируйте API-ключ проекта
API-ключ аутентифицирует ваш сервер при обращении к API проверки AgentBouncer. Он не является ключом подписи агента.
4
Передайте исходный URL запроса и заголовки подписи
URL должен совпадать с URL, который подписал агент. Сохраняйте заголовки Signature, Signature-Input и Signature-Agent.
5
Авторизуйте запрос с помощью allowed
Отклоняйте запрос только в том случае, если allowed имеет значение false.

Проверка запроса через REST

bash

curl -X POST https://agentbouncer.io/api/v1/verify \
  -H "Authorization: Bearer ab_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example/api/mcp/weather",
    "method": "POST",
    "headers": {
      "signature": "sig1=:BASE64_SIGNATURE:",
      "signature-input": "sig1=(\"@authority\" \"signature-agent\");created=176000;expires=176000030;keyid=\"KEY_ID\";tag=\"web-bot-auth\"",
      "signature-agent": "\"https://agent.example\"",
      "content-type": "application/json"
    },
    "expectedTag": "web-bot-auth",
    "action": "tools:call",
    "tool": "weather"
  }'

Применение итогового решения

typescript

const verification = await verifyWithAgentBouncer(request);

if (!verification.allowed) {
  return Response.json(
    {
      ok: false,
      error: "agent_access_denied",
      verification,
    },
    {
      status: verification.verified ? 403 : 401,
    }
  );
}

// Продолжите выполнение защищённой операции.
return runProtectedTool();

Основные понятия

Ключевые понятия

Узнайте, что такое проекты, API-ключи, ключи подписи, провайдеры и политики.

Понятие	Назначение
Проект	Защищённое приложение, API, MCP-сервер, origin или граница доверия.
API-ключ проекта	Аутентифицирует ваш сервер при обращении к /api/v1/verify.
Ключ подписи проекта	Идентифицирует один из ваших собственных агентов и подписывает его запросы.
Провайдер	Зарегистрированный внешний провайдер ИИ-агентов с идентификатором подписи и каталогом открытых ключей.
Ключ провайдера	Открытый ключ, найденный в каталоге подписей HTTP-сообщений провайдера.
Событие проверки	Неизменяемая запись о результате криптографической проверки, решении политики, подписанте, риске и метаданных запроса.
Политика	Правила, преобразующие информацию о проверке и доверии в allowed=true или allowed=false.

API-ключи и ключи подписи — это разные ключи

API-ключ проекта разрешает вашему серверу обращаться к AgentBouncer. Ключ подписи хранится у агента и используется для подписания исходного HTTP-запроса.

Панель управления

Создание проектов и управление ими

Настройте границу доверия для приложения или MCP-сервера.

1
Создайте проект
Выберите понятное название, например «Production MCP», «Checkout API» или «Внутрення автоматизация».
2
Укажите origin
Используйте публичный origin, к которому обращаются агенты. URL обратного прокси и внутренних развёртываний не должны заменять внешний подписанный URL.
3
Выберите политику
Начните с MONITOR_ONLY, изучите события проверки, а затем перейдите к BLOCK_UNKNOWN или более строгой политике.
4
При необходимости создайте ключи подписи проекта
Используйте ключи проекта для внутренних агентов, клиентов разработки и интеграций, принадлежащих проекту.
5
Просматривайте события
Проверяйте поля verified, allowed, reason, тип подписанта, провайдера, ключ проекта, действие, инструмент, риск и сведения о политике.

API-ключи проекта

Аутентифицируйте сервер при обращении к API AgentBouncer.

API-ключи проекта имеют префикс ab_live_ и должны храниться только на сервере. Никогда не размещайте их в браузерном JavaScript, публичных репозиториях или клиентских переменных окружения.

.env.local

bash

AGENTBOUNCER_API_KEY=ab_live_YOUR_API_KEY
AGENTBOUNCER_PUBLIC_ORIGIN=https://merchant.example
AGENTBOUNCER_VERIFY_URL=https://agentbouncer.io/api/v1/verify

Храните production-ключи в менеджере секретов вашего хостинг-провайдера.
Ротируйте ключ, если он случайно попал в журнал или репозиторий.
Не отправляйте API-ключ входящему ИИ-агенту.
Не путайте API-ключ AgentBouncer с приватным JWK подписи.

Интеграция

Интеграция с REST API

Вызывайте AgentBouncer из любого языка или серверного фреймворка.

POST /api/v1/verify

http

POST /api/v1/verify HTTP/1.1
Host: agentbouncer.io
Authorization: Bearer ab_live_YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://merchant.example/api/mcp/weather",
  "method": "POST",
  "headers": {
    "signature": "sig1=:...:",
    "signature-input": "sig1=(...);created=...;expires=...;keyid=\"...\";tag=\"web-bot-auth\"",
    "signature-agent": "\"https://agent.example\""
  },
  "expectedTag": "web-bot-auth",
  "action": "tools:call",
  "tool": "weather",
  "userAgent": "ExampleAgent/1.0"
}

Поле	Обязательность	Описание
url	Да	Точный внешний URL, запрос к которому был подписан.
method	Рекомендуется	Исходный HTTP-метод. По умолчанию используется GET.
headers	Рекомендуется	Исходные заголовки запроса, используемые для проверки подписи. Поля подписи также можно передать через signature, signatureInput и signatureAgent.
signature	Условно	Значение заголовка Signature. Обязательно, если оно не включено в headers.
signatureInput	Условно	Значение заголовка Signature-Input. Обязательно, если оно не включено в headers.
signatureAgent	Нет	Значение структурированного поля Signature-Agent. Его также можно включить в headers.
expectedTag	Нет	Тег назначения, ожидаемый защищённой конечной точкой.
action	Нет	Семантическая операция, например tools:call, products:read, checkout или orders:write.
tool	Нет	Инструмент MCP или возможность приложения, к которой выполняется обращение.
userAgent	Нет	Исходный User-Agent отправителя запроса для аналитики.

Сохраняйте подписанный URL

Не заменяйте публичный целевой URL адресом конечной точки проверки AgentBouncer, внутренним URL контейнера или URL обратного прокси.

Интеграция

SDK для JavaScript и TypeScript

Проверяйте подписанные запросы и применяйте итоговое решение политики AgentBouncer.

Установка

bash

npm install @agentbouncer/sdk

Создание клиента

typescript

import {
  createAgentBouncer,
} from "@agentbouncer/sdk";

export const agentBouncer =
  createAgentBouncer({
    apiKey:
      process.env.AGENTBOUNCER_API_KEY!,
    publicOrigin:
      process.env.AGENTBOUNCER_PUBLIC_ORIGIN,
    verifyUrl:
      process.env.AGENTBOUNCER_VERIFY_URL,
  });

Конструктор класса

SDK также экспортирует AgentBouncer. Вызовы new AgentBouncer(options) и createAgentBouncer(options) создают один и тот же тип клиента.

Настройте публичный origin при работе за прокси

Если request.url содержит внутренний URL развёртывания или обратного прокси, задайте в publicOrigin внешний origin, который подписывают агенты. В качестве альтернативы можно передавать targetUrl при каждом вызове verify().

verify()

typescript

const verification =
  await agentBouncer.verify({
    request,
    expectedTag: "web-bot-auth",
    action: "tools:call",
    tool: "weather",
  });

if (!verification.allowed) {
  return new Response(
    "Доступ агента запрещён",
    {
      status: verification.verified
        ? 403
        : 401,
    }
  );
}

// Продолжите выполнение защищённой операции.

require()

typescript

import {
  AgentBouncerDeniedError,
  AgentBouncerError,
} from "@agentbouncer/sdk";

try {
  const verification =
    await agentBouncer.require({
      request,
      expectedTag: "web-bot-auth",
      action: "tools:call",
      tool: "weather",
    });

  return runWeatherTool({
    agent: verification.agent,
  });
} catch (error) {
  if (
    error instanceof
    AgentBouncerDeniedError
  ) {
    return new Response(
      "Доступ агента запрещён",
      {
        status:
          error.verification.verified
            ? 403
            : 401,
      }
    );
  }

  if (
    error instanceof AgentBouncerError
  ) {
    return new Response(
      "Сервис проверки агента недоступен",
      {
        status: 503,
      }
    );
  }

  throw error;
}

Семантика методов SDK

Метод verify() возвращает полный результат проверки. Метод require() выбрасывает AgentBouncerDeniedError, если allowed имеет значение false. Ошибки сети, тайм-ауты, ошибки аутентификации API и некоректные ответы вызывают AgentBouncerError.

Интеграция

Next.js App Router

Защитите маршрут Next.js, сохранив внешний URL запроса.

src/lib/agentbouncer-client.ts

typescript

import {
  createAgentBouncer,
} from "@agentbouncer/sdk";

const apiKey =
  process.env.AGENTBOUNCER_API_KEY;

const publicOrigin =
  process.env.AGENTBOUNCER_PUBLIC_ORIGIN;

if (!apiKey) {
  throw new Error(
    "Не задан AGENTBOUNCER_API_KEY"
  );
}

if (!publicOrigin) {
  throw new Error(
    "Не задан AGENTBOUNCER_PUBLIC_ORIGIN"
  );
}

export const agentBouncer =
  createAgentBouncer({
    apiKey,
    publicOrigin,
    verifyUrl:
      process.env.AGENTBOUNCER_VERIFY_URL,
  });

src/app/api/mcp/weather/route.ts

typescript

import {
  AgentBouncerDeniedError,
  AgentBouncerError,
} from "@agentbouncer/sdk";
import {
  NextRequest,
  NextResponse,
} from "next/server";
import {
  agentBouncer,
} from "@/lib/agentbouncer-client";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export async function POST(
  req: NextRequest
) {
  const requestId = crypto.randomUUID();

  try {
    const verification =
      await agentBouncer.require({
        request: req,
        expectedTag: "web-bot-auth",
        action: "tools:call",
        tool: "weather",
      });

    const body = await req
      .json()
      .catch(() => ({}));

    const city =
      typeof body.city === "string"
        ? body.city
        : "Berlin";

    return NextResponse.json({
      ok: true,
      city,
      weather: {
        temperatureC: 21,
        conditions: "Ясно",
      },
      agent: verification.agent,
      requestId,
    });
  } catch (error) {
    if (
      error instanceof
      AgentBouncerDeniedError
    ) {
      return NextResponse.json(
        {
          ok: false,
          error: "mcp_access_denied",
          reason:
            error.verification.reason,
          requestId,
        },
        {
          status:
            error.verification.verified
              ? 403
              : 401,
        }
      );
    }

    console.error(
      "Не удалось выполнить проверку AgentBouncer",
      {
        requestId,
        error,
      }
    );

    return NextResponse.json(
      {
        ok: false,
        error:
          "agentbouncer_unavailable",
        message:
          error instanceof
          AgentBouncerError
            ? error.message
            : "Не удалось проверить запрос.",
        requestId,
      },
      {
        status: 503,
      }
    );
  }
}

Не используйте старую проверку доступа

Не используйте if (!verification.verified || !verification.allowed). Такая проверка ошибочно блокирует запросы, разрешённые режимом MONITOR_ONLY или настройкой allowUnsigned.

Интеграция

Next.js без SDK

Отправляйте минимальную полезную нагрузку проверки непосредственно в REST API.

Минимальный сбор заголовков

typescript

import type {
  NextRequest,
} from "next/server";
import {
  pickVerificationHeaders,
} from "./pick-verification-headers";

function resolvePublicTargetUrl(
  req: NextRequest
) {
  const publicOrigin =
    process.env
      .AGENTBOUNCER_PUBLIC_ORIGIN;

  if (!publicOrigin) {
    return req.nextUrl.toString();
  }

  return new URL(
    `${req.nextUrl.pathname}${req.nextUrl.search}`,
    publicOrigin
  ).toString();
}

export async function verifyAgentRequest(
  req: NextRequest,
  options?: {
    expectedTag?: string;
    action?: string;
    tool?: string;
  }
) {
  const targetUrl =
    resolvePublicTargetUrl(req);

  const response = await fetch(
    process.env.AGENTBOUNCER_VERIFY_URL ??
      "https://agentbouncer.io/api/v1/verify",
    {
      method: "POST",
      headers: {
        Authorization:
          `Bearer ${process.env.AGENTBOUNCER_API_KEY}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        url: targetUrl,
        method: req.method,
        headers:
          pickVerificationHeaders(req),
        expectedTag:
          options?.expectedTag ?? null,
        action:
          options?.action ?? null,
        tool:
          options?.tool ?? null,
        userAgent:
          req.headers.get("user-agent"),
      }),
      cache: "no-store",
    }
  );

  const result = await response
    .json()
    .catch(() => null);

  if (!response.ok) {
    throw new Error(
      result?.detail ||
        result?.reason ||
        `AgentBouncer вернул HTTP ${response.status}.`
    );
  }

  if (
    !result ||
    typeof result.verified !== "boolean" ||
    typeof result.allowed !== "boolean"
  ) {
    throw new Error(
      "AgentBouncer вернул некоректный ответ."
    );
  }

  return result;
}

Вызов конечной точки проверки

typescript

import type { NextRequest } from "next/server";
import { pickVerificationHeaders } from "./pick-verification-headers";

export async function verifyAgentRequest(
  req: NextRequest,
  options?: {
    expectedTag?: string;
    action?: string;
    tool?: string;
  }
) {
  const targetUrl = req.nextUrl.toString();

  const response = await fetch(
    process.env.AGENTBOUNCER_VERIFY_URL ??
      "https://agentbouncer.io/api/v1/verify",
    {
      method: "POST",
      headers: {
        Authorization:
          `Bearer ${process.env.AGENTBOUNCER_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        url: targetUrl,
        method: req.method,
        headers: pickVerificationHeaders(req),
        expectedTag: options?.expectedTag ?? null,
        action: options?.action ?? null,
        tool: options?.tool ?? null,
        userAgent: req.headers.get("user-agent"),
      }),
      cache: "no-store",
    }
  );

  const result = await response.json();

  if (!response.ok && response.status === 401) {
    throw new Error(
      "Не удалось пройти аутентификацию API AgentBouncer."
    );
  }

  return result;
}

Интеграция

Интеграция с Express

Защищайте маршруты Express с помощью REST API проверки.

typescript

import type {
  NextFunction,
  Request,
  Response,
} from "express";

export async function requireVerifiedAgent(
  req: Request,
  res: Response,
  next: NextFunction
) {
  try {
    const protocol =
      req.headers["x-forwarded-proto"] || req.protocol;

    const host =
      req.headers["x-forwarded-host"] ||
      req.headers.host;

    const targetUrl =
      `${protocol}://${host}${req.originalUrl}`;

    const verifyResponse = await fetch(
      "https://agentbouncer.io/api/v1/verify",
      {
        method: "POST",
        headers: {
          Authorization:
            `Bearer ${process.env.AGENTBOUNCER_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          url: targetUrl,
          method: req.method,
          headers: {
            signature: req.headers.signature,
            "signature-input":
              req.headers["signature-input"],
            "signature-agent":
              req.headers["signature-agent"],
            "content-type":
              req.headers["content-type"],
            "content-digest":
              req.headers["content-digest"],
          },
          expectedTag: "web-bot-auth",
          action: "api:call",
        }),
      }
    );

    const verification = await verifyResponse.json();

    if (!verification.allowed) {
      res.status(verification.verified ? 403 : 401).json({
        ok: false,
        error: "agent_access_denied",
        verification,
      });

      return;
    }

    res.locals.agentVerification = verification;
    next();
  } catch (error) {
    next(error);
  }
}

Интеграция

Защита инструментов MCP

Применяйте решения AgentBouncer до выполнения операций MCP.

Укажите для action значение tools:call, а для tool — имя инструмента MCP. Благодаря этому события проверки и правила пользовательской политики будут относиться к конкретной запрашиваемой операции.

Шаблон авторизации MCP

typescript

const verification = await agentBouncer.verify({
  request,
  expectedTag: "web-bot-auth",
  action: "tools:call",
  tool: toolName,
});

if (!verification.allowed) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: "Этому агенту запрещён вызов инструмента.",
      },
    ],
  };
}

switch (toolName) {
  case "weather":
    return getWeather(toolArguments);

  case "catalog":
    return searchCatalog(toolArguments);

  case "checkout":
    return createCheckout(toolArguments);

  default:
    throw new Error("Неизвестный инструмент MCP");
}

Операция	Рекомендуемое действие	Рекомендуемый инструмент
Чтение ресурса MCP	resources:read	имя ресурса
Получение списка инструментов	tools:list	*
Вызов инструмента	tools:call	имя инструмента
Чтение товаров	products:read	catalog
Создание оформления заказа	checkout:create	checkout
Отправка заказа	orders:create	orders

Идентификаторы агентов

Ключи подписи проекта

Создавайте идентификаторы для агентов, непосредственно принадлежащих вашему проекту.

1
Выпустите ключ проекта
Откройте вкладку Agent keys проекта и создайте ключ с понятным названием, например «Production MCP agent» или «Internal CRM».
2
Сохраните приватный JWK
Приватный ключ показывается только один раз. Сохраните его в менеджере секретов агента.
3
Сохраните публичный идентификатор
AgentBouncer хранит открытый JWK, идентификатор ключа, идентификатор Signature-Agent, области доступа и конфигурацию политики.
4
Подписывайте запросы
Используйте приватный JWK для создания заголовков Signature и Signature-Input для точного целевого URL.
5
Отзывайте скомпрометированные ключи
Немедленно удалите или отзовите ключ проекта, если его приватный JWK был раскрыт.

Пример переменных окружения

bash

AGENT_KEY_ID=YOUR_KEY_ID
AGENT_SIGNATURE_AGENT=https://agentbouncer.io/project-agents/PROJECT_ID/KEY_ID
AGENT_PRIVATE_JWK='{"kty":"OKP","crv":"Ed25519","x":"...","d":"..."}'

Идентификаторы агентов

Регистрация провайдера агентов

Опубликуйте идентификатор провайдера и каталог открытых ключей.

1
Создайте провайдера
Выберите постоянный slug, название провайдера, веб-сайт, origin Signature-Agent и URL каталога.
2
Опубликуйте открытый JWKS
Разместите открытые ключи в настроенном каталоге подписей HTTP-сообщений.
3
Обновите ключи
Запросите у AgentBouncer загрузку и проверку каталога.
4
Подтвердите домен провайдера
Опубликуйте DNS TXT-запись AgentBouncer или файл подтверждения.
5
Подписывайте production-запросы
Используйте приватный ключ, соответствующий активному открытому ключу в каталоге.

Пример документа JWKS

json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "kid": "provider-key-2026-01",
      "alg": "EdDSA",
      "use": "sig",
      "x": "PUBLIC_KEY_MATERIAL"
    }
  ]
}

Рекомендуемый публичный адрес

text

https://agent.example/.well-known/http-message-signatures-directory/jwks.json

Никогда не публикуйте приватный JWK

Каталог провайдера должен содержать только публичные свойства JWK. Приватное свойство d должно оставаться секретным.

Авторизация

Режимы политик

Выберите, как проверенный идентификатор и данные о доверии влияют на доступ.

Режим	Поведение
MONITOR_ONLY	Регистрирует ошибки проверки и политики, но разрешает запрос.
BLOCK_UNKNOWN	Блокирует неподписанные запросы и неизвестные идентификаторы.
ALLOW_TIER_1_ONLY	Разрешает доступ только провайдерам с наивысшим уровнем доверия.
ALLOW_TIER_1_AND_2	Разрешает доступ доверенным провайдерам уровней Tier 1 и Tier 2.
CUSTOM	Оценивает правила провайдера, уровня доверия, ключа проекта, действия и инструмента. Совпавшие правила DENY имеют приоритет над совпавшими правилами ALLOW; если совпадений нет, применяется defaultEffect.

Пользовательские политики

Создавайте детальные разрешающие и запрещающие правила.

Пример пользовательской политики

json

{
  "version": 1,
  "defaultEffect": "DENY",
  "rules": [
    {
      "id": "rule_allow_tier_1_read",
      "name": "Разрешить Tier 1 чтение каталога",
      "enabled": true,
      "effect": "ALLOW",
      "subject": {
        "type": "PROVIDER_TIER",
        "tiers": ["TIER_1"]
      },
      "actions": ["products:read"],
      "tools": ["catalog"]
    },
    {
      "id": "rule_deny_external_checkout",
      "name": "Запретить внешнее оформление заказа",
      "enabled": true,
      "effect": "DENY",
      "subject": {
        "type": "ANY_PROVIDER"
      },
      "actions": ["checkout:create"],
      "tools": ["checkout"]
    }
  ]
}

Правила DENY имеют приоритет над правилами ALLOW.
Пустой массив actions соответствует любому действию.
Пустой массив tools соответствует любому инструменту.
Подстановочный символ * соответствует любому действию или инструменту.
Если ни одно правило не совпало, применяется defaultEffect.
Используйте PROJECT_KEY для выбора конкретных ключей внутренних агентов.

Справочник API

Ответ проверки

Изучите поля, возвращаемые API проверки.

json

{
  "verified": true,
  "allowed": true,
  "reason": null,
  "checks": {
    "signature": "valid",
    "timestamp": "valid",
    "replay": "unknown",
    "provider": "known",
    "policy": "matched"
  },
  "agent": {
    "type": "PROJECT_KEY",
    "provider": null,
    "providerSlug": null,
    "projectKey": {
      "id": "key_id",
      "name": "Production MCP agent",
      "scopes": []
    },
    "signatureAgent": "https://agentbouncer.io/project-agents/...",
    "keyid": "..."
  },
  "request": {
    "method": "POST",
    "path": "/api/mcp/weather",
    "tag": "web-bot-auth",
    "expectedTag": "web-bot-auth",
    "action": "tools:call",
    "tool": "weather"
  },
  "risk": {
    "score": 5,
    "level": "low"
  },
  "policy": {
    "mode": "CUSTOM",
    "wouldBlockReason": null,
    "matchedRule": {
      "id": "rule_allow_weather",
      "name": "Разрешить погодного агента",
      "effect": "ALLOW"
    },
    "defaultEffectApplied": false
  }
}

Обнаружение повторных запросов

Действительная подпись сама по себе не доказывает, что запрос не был воспроизведён повторно. Пока не включено хранилище защиты от повторов или проверка nonce, поле checks.replay возвращает unknown.

Поле	Значение
verified	Указывает, была ли успешно выполнена криптографическая проверка идентификатора.
allowed	Итоговое решение об авторизации после применения политики проекта.
reason	Фактическая причина отказа или null, если доступ разрешён.
checks	Отдельные результаты проверки подписи, временной метки, повтора, провайдера, ключа проекта и политики. Значение unknown означает, что проверка не выполнялась или для неё не хватило информации.
agent	Определённый идентификатор провайдера или ключа проекта.
risk	Рассчитанная оценка и уровень риска.
policy	Режим политики, совпавшее правило и гипотетическая причина блокировки.

Справочник API

Причины и ошибки

Распространённые причины результатов проверки и решений политики.

Причина	Описание
unauthorized	API-ключ проекта AgentBouncer отсутствует или недействителен.
invalid_request	В полезной нагрузке проверки отсутствует обязательное поле.
invalid_url	Поле url не является допустимым абсолютным целевым URL.
no_signature	Отсутствует заголовок Signature или Signature-Input.
no_keyid	Заголовок Signature-Input не содержит keyid.
unknown_keyid	Активный ключ проекта или провайдера не найден.
not_yet_valid	Время создания подписи находится в будущем.
expired	Срок действия подписи истёк.
window_too_long	Период действия подписи от created до expires превышает допустимый максимум.
bad_signature	Криптографическая проверка завершилась неудачно.
unknown_provider	Провайдер ключа не распознан.
provider_blocked	Провайдер приостановлен, заблокирован, признан мошенническим или отозван.
provider_not_trusted	Проект требует доверенного провайдера.
unsupported_tag	Тег назначения подписи не поддерживается.
tag_mismatch	Фактический тег подписи не соответствует expectedTag.
tier_too_low	Провайдер не соответствует требуемому уровню доверия.
trust_score_too_low	Оценка доверия провайдера ниже порогового значения проекта.
project_keys_disabled	Ключи подписи, принадлежащие проекту, отключены.
custom_policy_denied	Совпавшее пользовательское правило DENY отклонило запрос.
custom_policy_no_match	Ни одно пользовательское правило не совпало, а эффект по умолчанию установлен в DENY.

Эксплуатация

События проверки

Отслеживайте реальный трафик и расследуйте решения об авторизации.

Фильтруйте события по дню, неделе, месяцу, всему периоду или произвольному диапазону дат.
Сравнивайте проверенные запросы с разрешёнными запросами.
При обозначении события как принятого или отклонённого используйте allowed, а не verified.
Проверяйте уровень и статус провайдера, оценку доверия, оценку злоупотреблений, риск, действие и инструмент.
Просматривайте wouldBlockReason для запросов, разрешённых режимом MONITOR_ONLY.
Экспортируйте данные событий в CSV для автономного анализа.

verified	allowed	Рекомендуемая метка интерфейса
true	true	Разрешён
true	false	Запрещён политикой
false	true	Разрешён в режиме мониторинга
false	false	Проверка не пройдена

Эксплуатация

Устранение неполадок

Диагностируйте проблемы с подписью, URL, каталогом ключей и политикой.

Проблема	Что проверить
Некоректный заголовок Signature	Убедитесь, что Signature, Signature-Input и Signature-Agent переданы ровно по одному разу.
bad_signature	Сравните подписанный URL, метод, authority, охватываемые компоненты, открытый ключ и дайджест содержимого.
unknown_keyid	Убедитесь, что ключ проекта активен, или обновите каталог открытых ключей провайдера.
tag_mismatch	Сравните expectedTag с тегом в Signature-Input.
custom_policy_no_match	Проверьте тип субъекта, идентификатор ключа проекта, уровень провайдера, действие, инструмент и defaultEffect.
MONITOR_ONLY продолжает блокировать запросы	Убедитесь, что приложение проверяет только verification.allowed.
Неверный @authority	Используйте внешний хост, который подписал агент, а не внутренний хост развёртывания.

Правильная проверка авторизации

typescript

if (!verification.allowed) {
  return Response.json(
    {
      ok: false,
      error: "agent_access_denied",
      verification,
    },
    {
      status: verification.verified ? 403 : 401,
    }
  );
}

Неправильная проверка авторизации

typescript

// Неправильно: блокирует запросы в режиме MONITOR_ONLY.
if (!verification.verified || !verification.allowed) {
  return new Response("Доступ запрещён", {
    status: 403,
  });
}

Эксплуатация

Контрольный список перед запуском

Проверьте интеграцию перед включением блокирующих политик.

API-ключ AgentBouncer хранится только на сервере.
Production-проект использует правильный публичный origin.
Приложение отправляет точный подписанный целевой URL.
Заголовки подписи передаются ровно по одному разу.
Конфиденциальные и инфраструктурные заголовки исключены.
Проверка авторизации использует allowed.
Действия и имена инструментов MCP заполнены.
Трафик MONITOR_ONLY был проанализирован.
Известные провайдеры и ключи проекта определяются правильно.
Пользовательские политики имеют намеренно выбранный эффект по умолчанию.
Приватные ключи подписи хранятся в менеджере секретов.
Процедуры отзыва и ротации ключей документированы.
Экспорт событий проверки протестирован.

Проверяйте AI-агентов до предоставления доступа к API

Обзор AgentBouncer

Самое важное правило интеграции

Быстрый старт

Создайте проект

Начните с режима мониторинга

Скопируйте API-ключ проекта

Передайте исходный URL запроса и заголовки подписи

Авторизуйте запрос с помощью allowed

Ключевые понятия

API-ключи и ключи подписи — это разные ключи

Создание проектов и управление ими

Создайте проект

Укажите origin

Выберите политику

При необходимости создайте ключи подписи проекта

Просматривайте события

Рекомендуемые границы проектов

API-ключи проекта

Интеграция с REST API

Сохраняйте подписанный URL

SDK для JavaScript и TypeScript

Конструктор класса

Настройте публичный origin при работе за прокси

Семантика методов SDK

Next.js App Router

Не используйте старую проверку доступа

Next.js без SDK

Интеграция с Express

Защита инструментов MCP

Ключи подписи проекта

Выпустите ключ проекта

Сохраните приватный JWK

Сохраните публичный идентификатор

Подписывайте запросы

Отзывайте скомпрометированные ключи

Регистрация провайдера агентов

Создайте провайдера

Опубликуйте открытый JWKS

Обновите ключи

Подтвердите домен провайдера

Подписывайте production-запросы

Никогда не публикуйте приватный JWK

Режимы политик

Рекомендуемый порядок внедрения

Пользовательские политики

Ответ проверки

Обнаружение повторных запросов

Причины и ошибки

События проверки

Рекомендации по безопасности

Целостность тела запроса

Устранение неполадок

Контрольный список перед запуском