agentsready
API / Auth / MCP Средне

auth.md: собственный путь регистрации для агентов

Что такое auth.md (открытый протокол WorkOS), зачем агентам собственный onboarding вместо имитации кликов, минимальный пример файла, правильно vs неправильно, ошибки и как проверить.

Обновлено:

Что это

auth.md — открытый протокол (запущен WorkOS в мае 2026), который даёт AI-агентам собственный путь регистрации в сервисе. Вместо имитации человека — кликов по формам, разгадывания CAPTCHA, подтверждений по email — агент читает один markdown-файл по адресу /auth.md и узнаёт: какие потоки регистрации поддерживаются, какие scopes существуют и какие endpoint вызвать.

Файл читаем и человеком, и агентом. Протокол не изобретает новую криптографию — он композирует существующие стандарты: OAuth Protected Resource Metadata (RFC 9728) и identity-assertions. Контроль остаётся за приложением: вы решаете, какие потоки принимать и какие права выдавать.

Зачем это AI-агентам

Двадцать лет онбординг строился под человека за браузером. Агент ломает это предположение: ему нужен не «хрупкий хак с автоматизацией браузера», а предсказуемый машинный путь. auth.md отвечает на три вопроса агента: как мне зарегистрироваться, какие scopes я могу запросить, как доказать, что пользователь это одобрил.

Два основных потока:

  • Agent Verified — провайдер агента (например, платформа, которой вы доверяете) подтверждает личность пользователя; сервис верифицирует и выдаёт учётные данные. Без переписки по email.
  • User Claimed — агент регистрируется первым, затем пользователь подтверждает его одноразовым кодом (OTP). Работает даже там, где платформа агента пока не умеет подтверждать личность — подходит для MCP-серверов, кастомных агентов и скриптов поверх LLM-API.

Минимальный рабочий пример

GET /auth.md HTTP/1.1
# Agent registration

This service supports agent registration via the auth.md protocol.

## Supported flows
- **Agent Verified** — your agent provider attests the user's identity.
- **User Claimed** — register first, the user confirms with an OTP code.

## Scopes
- `read:profile` — read the user's public profile
- `write:orders` — create orders on the user's behalf

## How to register
POST https://api.example.com/agents/register

OAuth metadata: /.well-known/oauth-protected-resource

Опубликуйте файл с Content-Type: text/markdown (или text/plain) в корне домена, рядом с готовым /.well-known/oauth-protected-resource.

Правильно vs неправильно

ПравильноНеправильно
/auth.md в корне доменаФайл спрятан в подкаталоге
Реальный markdown с потоками/scopesSPA отдаёт index.html на любой путь
Ссылка на /.well-known/oauth-protected-resourceРегистрация описана, но OAuth-метаданных нет
Указаны конкретные scopes и endpoint«Свяжитесь с нами» вместо машинного пути

Типичные ошибки

  • SPA-fallback. Сайт на клиентском роутинге отдаёт 200 OK и HTML-страницу на /auth.md. Для агента это не auth.md — отдавайте настоящий markdown.
  • Файл есть, но пустой по смыслу — без потоков, scopes и endpoint агенту не за что зацепиться.
  • Нет связки с OAuth. auth.md опирается на RFC 9728 — без /.well-known/oauth-protected-resource цепочка авторизации обрывается.
  • Регистрация только для людей. Если единственный путь — веб-форма с CAPTCHA, агент всё ещё заблокирован.

Как проверить

Наш скан запрашивает /auth.md и проверяет, что это похоже на настоящий auth.md, а не на HTML-заглушку. Вручную:

curl -s https://example.com/auth.md | head -40

Ждём markdown с описанием потоков регистрации, scopes и endpoint. Проверка auth_md — информационная: её отсутствие не снижает балл (протокол молодой), но раннее внедрение даёт преимущество, пока конкуренты ещё имитируют клики.

Источники