# auth-md

## Что такое auth.md?

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

```markdown
# 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` — **информационная**: её отсутствие не снижает балл (протокол
молодой), но наличие даёт бонус за раннее внедрение. Сам процесс регистрации
сканер не выполняет.

[← Все термины глоссария](/glossary)