API / Auth / MCP
auth.md
Markdown-файл /auth.md (открытый протокол WorkOS), описывающий AI-агентам, как зарегистрироваться в сервисе: потоки, scopes и endpoint.
Что такое auth.md?
auth.md — открытый протокол (запущен WorkOS в мае 2026) для регистрации
AI-агентов в веб-сервисах. Приложение публикует markdown-файл по адресу
/auth.md, который сообщает агенту, как зарегистрироваться: какие потоки
поддерживаются, какие scopes существуют и какие endpoint вызывать. Файл читаем
и человеком, и агентом.
# Agent registration
## Supported flows
- Agent Verified — provider attests the user's identity
- User Claimed — register first, user confirms via OTP
## Scopes
- read:profile
- write:orders
## How to register
POST https://api.example.com/agents/register
OAuth metadata: /.well-known/oauth-protected-resourceЗачем нужен auth.md?
Десятилетиями регистрация строилась под человека: формы, CAPTCHA, подтверждения по email, экраны согласия OAuth. Агенты ломают это предположение — им нужен собственный, машиночитаемый путь, а не имитация кликов в браузере.
auth.md даёт его, композируя существующие стандарты (OAuth Protected Resource
Metadata, RFC 9728, и identity-assertions), а не вводя новый «закрытый сад».
Протокол открытый: любое приложение может опубликовать auth.md, любой агент —
прочитать, без аккаунта WorkOS. Контроль остаётся за приложением: оно решает,
какие потоки принимать и какие права выдавать.
Как реализовать auth.md?
Опубликуйте markdown-файл в корне домена с Content-Type: text/markdown (или
text/plain). Содержание (строгой JSON-схемы у протокола нет — это
markdown-конвенции):
| Раздел | Назначение |
|---|---|
| Потоки (flows) | Agent Verified и/или User Claimed |
| Scopes | какие права агент может запросить |
| Регистрация | endpoint и метод (register_uri) |
| OAuth | ссылка на /.well-known/oauth-protected-resource |
Опционально — блок agent_auth в /.well-known/oauth-authorization-server
с register_uri, типами идентичности и учётных данных, URL claim/revocation.
Как мы проверяем auth.md?
Сканер выполняет GET-запрос на /auth.md и проверяет, что это похоже на
настоящий auth.md, а не на HTML-заглушку:
- HTTP-статус 200 и непустое тело;
- это не SPA-fallback (HTML вместо markdown);
- присутствуют маркеры протокола (потоки, scopes, регистрация, OAuth).
Проверка auth_md — информационная: её отсутствие не снижает балл (протокол
молодой), но наличие даёт бонус за раннее внедрение. Сам процесс регистрации
сканер не выполняет.