APIs e autenticação: API Catalog, OAuth e auth.md

Aula 1

API Catalog (RFC 9727)

A RFC 9727, publicada em 2025 pelo grupo HTTPAPI da IETF, registra o endereço /.well-known/api-catalog e a relação rel="api-catalog". O catálogo é um documento que lista as APIs públicas de um domínio e aponta, para cada uma, a especificação legível por máquina (OpenAPI, AsyncAPI), a documentação, o status e a política de uso. É o "sitemap das APIs".

O formato obrigatório é o linkset em JSON (RFC 9264), com o tipo application/linkset+json e o parâmetro de perfil da RFC 9727.

HTTP/1.1 200 OK
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

{
  "linkset": [
    {
      "anchor": "https://api.exemplo.com.br/v1/",
      "service-desc": [
        { "href": "https://api.exemplo.com.br/v1/openapi.json",
          "type": "application/vnd.oai.openapi+json" }
      ],
      "service-doc": [
        { "href": "https://exemplo.com.br/docs/api", "type": "text/html" }
      ],
      "status": [
        { "href": "https://api.exemplo.com.br/v1/health" }
      ]
    }
  ]
}

• Cada objeto do linkset tem um anchor (a API descrita) e listas de links por relação.
• service-desc aponta a descrição para máquinas; service-doc, a documentação para humanos; status, um endpoint de saúde; service-meta, metadados como política e termos.
• Para catálogos grandes, use a relação item para apontar outros catálogos ou APIs, criando uma hierarquia.
• A RFC pede suporte a HEAD e a anúncio do catálogo com o cabeçalho Link: </.well-known/api-catalog>; rel="api-catalog" nas respostas do domínio.

Fontes desta aula: RFC 9727: api-catalog · RFC 9264: Linkset

Aula 2

Descoberta de OAuth e OpenID Connect (RFC 8414)

Agentes que atuam em nome de um usuário não devem receber senhas. O caminho correto é o OAuth: o usuário autoriza, o agente recebe um token com escopo limitado e pode ser revogado. Para isso funcionar sem configuração manual, o agente precisa descobrir os endpoints do servidor de autorização. Há dois documentos para isso, e o relatório de exemplo verifica os dois.

{
  "issuer": "https://login.exemplo.com.br",
  "authorization_endpoint": "https://login.exemplo.com.br/oauth/authorize",
  "token_endpoint": "https://login.exemplo.com.br/oauth/token",
  "registration_endpoint": "https://login.exemplo.com.br/oauth/register",
  "jwks_uri": "https://login.exemplo.com.br/.well-known/jwks.json",
  "scopes_supported": ["pedidos:ler", "pedidos:criar"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "client_id_metadata_document_supported": true
}

Os campos mais importantes para agentes são code_challenge_methods_supported (a especificação de autorização do MCP exige PKCE com S256 e manda o cliente recusar servidores que não anunciam esse campo), registration_endpoint (registro dinâmico) e client_id_metadata_document_supported (aula 4). O issuer deve ser idêntico à URL base do documento.

Se você usa um provedor de identidade pronto, como Auth0, Keycloak, Cognito ou Google, esses documentos já existem no domínio do provedor. O trabalho, então, é apontar para eles a partir do seu recurso, que é o assunto da próxima aula.

Fontes desta aula: RFC 8414: OAuth 2.0 Authorization Server Metadata · OpenID Connect Discovery 1.0 · MCP: Authorization

Aula 3

Metadados de recurso protegido (RFC 9728)

A RFC 9728 (OAuth 2.0 Protected Resource Metadata, abril de 2025) resolve um problema prático: o agente chega a uma API e recebe um 401. Qual servidor de autorização emite tokens para ela? Que escopos existem? A resposta fica em /.well-known/oauth-protected-resource, publicado pelo próprio recurso.

{
  "resource": "https://api.exemplo.com.br",
  "authorization_servers": ["https://login.exemplo.com.br"],
  "scopes_supported": ["pedidos:ler", "pedidos:criar"],
  "bearer_methods_supported": ["header"],
  "resource_name": "API de pedidos",
  "resource_documentation": "https://exemplo.com.br/docs/api"
}

O segundo mecanismo da RFC está na resposta de erro. Quando o recurso nega acesso, ele indica onde estão os metadados:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.exemplo.com.br/.well-known/oauth-protected-resource"

Repare no relatório de exemplo: a requisição GET / retornou 200 sem WWW-Authenticate, e o metadado deu 404. Para um site sem área protegida, isso é esperado. Para um site com API ou área logada, a cadeia completa é: 401 com resource_metadata → metadados do recurso → authorization_servers → metadados do servidor (RFC 8414) → fluxo OAuth com PKCE.

Essa cadeia é exatamente a que a especificação de autorização do MCP adotou: servidores MCP devem implementar a RFC 9728, e clientes devem tentar tanto oauth-authorization-server quanto openid-configuration. Por isso, quem prepara a autenticação seguindo este módulo já deixa o terreno pronto para publicar um servidor MCP.

Fontes desta aula: RFC 9728: Protected Resource Metadata · specification.website: oauth-protected-resource

Aula 4

Registro de clientes e auth.md

Como um agente vira cliente OAuth

No OAuth tradicional, cada aplicação é registrada à mão e recebe um client_id. Com milhares de agentes diferentes, isso não escala. Há três caminhos, na ordem de preferência da especificação do MCP:

1. Cliente pré-registrado: funciona para parceiros conhecidos.
2. Client ID Metadata Documents (CIMD): o client_id é uma URL HTTPS que aponta para um JSON com os metadados do cliente (nome, URIs de retorno, logo). O servidor busca e valida esse documento. Não há registro prévio, e o domínio do cliente funciona como identidade.
3. Registro dinâmico (RFC 7591): o agente faz POST no registration_endpoint e recebe um client_id. É flexível, mas abre a porta para registros em massa e exige limites.

auth.md: autenticação explicada para agentes

Os metadados OAuth dizem onde estão os endpoints, mas não explicam regras de negócio: se é preciso ter conta antes, se existe período de teste, que escopo pedir para cada tarefa, como obter uma chave de API para uso sem usuário. O auth.md, convenção proposta pela WorkOS, é um arquivo Markdown público na raiz do site (/auth.md) que explica, em linguagem natural, como um agente deve se cadastrar e se autenticar.

# Autenticação para agentes de IA: Exemplo

## Visão geral
A API usa OAuth 2.1 com PKCE. Metadados:
- Recurso: https://api.exemplo.com.br/.well-known/oauth-protected-resource
- Servidor: https://login.exemplo.com.br/.well-known/oauth-authorization-server

## Registro do cliente
Aceitamos Client ID Metadata Documents. Use a URL do seu documento como client_id.

## Escopos
- pedidos:ler: consultar pedidos do usuário (sem alterações)
- pedidos:criar: criar pedidos (requer confirmação do usuário)

## Sem usuário
Chaves de API para leitura de catálogo: https://exemplo.com.br/desenvolvedores

O auth.md não tem campos obrigatórios. A regra é descrever só o que você realmente implementa, com links para os metadados oficiais. Ele é uma convenção recente, de uma empresa, sem status de padrão, mas aparece nos scanners de prontidão e tem custo baixo para quem já tem OAuth.

Fontes desta aula: RFC 7591: Dynamic Client Registration · WorkOS: auth.md · specification.website: auth.md

Erros comuns

• issuer diferente da URL do documento. Clientes rigorosos rejeitam o servidor.
• 401 sem WWW-Authenticate. O agente não tem como descobrir o servidor de autorização.
• Sem PKCE S256 anunciado. Clientes MCP recusam o servidor.
• Registro dinâmico aberto sem limites. Aplique limites de taxa, expiração de clientes não usados e revisão de escopos.
• Escopos genéricos demais. Um escopo admin para tudo faz o usuário autorizar mais do que o agente precisa. Separe leitura de escrita.
• api-catalog com tipo errado. Deve ser application/linkset+json, não application/json.

Aplicação prática: monte a cadeia de descoberta

1. Liste as APIs públicas do domínio e publique /.well-known/api-catalog com service-desc para cada uma.
2. Se há área logada ou API protegida, publique /.well-known/oauth-protected-resource e faça o 401 enviar resource_metadata.
3. Confirme que o servidor de autorização expõe RFC 8414 ou OIDC Discovery com PKCE S256.
4. Escreva o /auth.md com o fluxo, os escopos e os links.
5. Teste a cadeia completa com um cliente MCP ou com curl, partindo apenas do domínio.

Siglas e termos deste módulo

OAuth:

Protocolo de autorização delegada: o usuário autoriza uma aplicação sem entregar a senha.

OIDC:

OpenID Connect, camada de identidade sobre o OAuth.

PKCE:

Proof Key for Code Exchange, proteção do fluxo de código de autorização (S256).

DCR:

Dynamic Client Registration, registro dinâmico de clientes (RFC 7591).

CIMD:

Client ID Metadata Document, client_id que é uma URL de metadados.

Linkset:

Formato de conjunto de links em JSON (RFC 9264).

OpenAPI:

Especificação padrão para descrever APIs HTTP.