Auth.md

Visão Geral

O protocolo auth.md é um padrão aberto que permite agentes de IA se registrarem em serviços em nome de usuários, sem formulários de signup. Um arquivo Markdown publicado na raiz do serviço (https://service.com/auth.md) funciona simultaneamente como documentação legível por humanos e artefato descobrível por agentes em runtime.

Estende o RFC 9728 (OAuth 2.0 Protected Resource Metadata) com um bloco agent_auth nos metadados do Authorization Server.

Quando Usar

• Tornar sua app agent-ready publicando um auth.md
• Gerar Protected Resource Metadata (RFC 9728)
• Validar um auth.md existente contra a especificação
• Implementar endpoints de registro de agentes
• Entender como o protocolo auth.md funciona
• Configurar fluxos de autenticação para agentes

Instalação

npx skills add https://gitlab.com/fabriciotelles/skills -s auth-md

Fluxos Suportados

Fluxo	Mecanismo	Quando usar
Agent Verified	Provider assina um ID-JAG atestando identidade do usuário	JIT provisioning de OIDC/SAML; zero-friction
User Claimed	OTP-based (anonymous start ou email required)	Plataformas sem ID-JAG; self-serve

Endpoints do Protocolo

Endpoint	Propósito
/.well-known/oauth-protected-resource	Discovery — resource metadata
/.well-known/oauth-authorization-server	Discovery — AS metadata com bloco agent_auth
POST /agent/auth	Registro — despacha por campo type
POST /agent/auth/claim	Início de claim (anonymous start)
POST /agent/auth/claim/complete	Verificação OTP
POST /agent/auth/revoke	Revogação

Modos de Operação

Modo	Descrição
generate	Cria auth.md + metadata JSON
validate	Verifica auth.md existente (basic ou full com fetch live)
explain	Explica o protocolo sem gerar artefatos

Artefatos Gerados

1. auth.md — Arquivo Markdown com todos os passos do protocolo
2. oauth-protected-resource.json — JSON para /.well-known/oauth-protected-resource
3. oauth-authorization-server.json — JSON com bloco agent_auth completo

Origem

Protocolo criado por WorkOS. Spec: github.com/workos/auth.md

📄 Documentação completa no GitLab