--- # ============================================================================ # Auth.md — WorkOS / Agent Skills Discovery (YAML frontmatter) # https://workos.com/auth-md / https://agentskills.io # ============================================================================ title: Sentinel Brand — Agent Authentication & Registration summary: OAuth 2.0 + DCR registration for AI agents accessing Sentinel Brand APIs (brand monitoring, sentiment analysis, crisis alerts, news clipping). version: 1.0.0 provider: name: Sentinel Brand url: https://sentinelbrand.com.br contact: agents@sentinelbrand.com.br documentation: https://sentinelbrand.com.br/auth.md discovery: oauth_authorization_server: https://sentinelbrand.com.br/.well-known/oauth-authorization-server oauth_protected_resource: https://sentinelbrand.com.br/.well-known/oauth-protected-resource api_catalog: https://sentinelbrand.com.br/.well-known/api-catalog agent_skills_index: https://sentinelbrand.com.br/.well-known/agent-skills/index.json mcp_server_card: https://sentinelbrand.com.br/.well-known/mcp/server-card.json robots_txt: https://sentinelbrand.com.br/robots.txt agent_auth: registration_methods: - dynamic - manual - oidc register_uri: https://sentinelbrand.com.br/oauth/agents/register manual_uri: https://sentinelbrand.com.br/oauth/agents/register/manual client_update_uri: https://sentinelbrand.com.br/oauth/agents/client revocation_uri: https://sentinelbrand.com.br/oauth/agents/revoke claims_endpoint: https://sentinelbrand.com.br/oauth/agents/claims supported_identity_types: - client-id - did:web - oidc - email supported_credential_types: - access_token - bearer - dpop - refresh_token - id_token supported_scopes: - mentions:read - sentiment:read - alerts:read - alerts:write preferred_grant_types: - client_credentials - authorization_code - urn:ietf:params:oauth:grant-type:device_code dpop_required: false pke_required: false tos_uri: https://sentinelbrand.com.br/#termos policy_uri: https://sentinelbrand.com.br/#privacidade --- # Auth.md — Sentinel Brand Agent Registration ## Overview Sentinel Brand oferece APIs para **monitoramento de marca**, **análise de sentimento**, **clipping de notícias** e **gestão de crise** de reputação digital. Agentes de IA podem se registrar dinamicamente (RFC 7591) ou manualmente para obter credenciais OAuth 2.0 e consumir os recursos. Documentação de referência: `https://workos.com/auth-md` --- ## Endpoints de Descoberta (basta bater nessas URLs) | Recurso | URL | Tipo | |---|---|---| | Authorization Server (RFC 8414) | `https://sentinelbrand.com.br/.well-known/oauth-authorization-server` | `application/json` | | Protected Resource (RFC 9728) | `https://sentinelbrand.com.br/.well-known/oauth-protected-resource` | `application/json` | | API Catalog (RFC 9727) | `https://sentinelbrand.com.br/.well-known/api-catalog` | `application/linkset+json` | | Agent Skills Index | `https://sentinelbrand.com.br/.well-known/agent-skills/index.json` | `application/json` | | MCP Server Card (SEP-1649) | `https://sentinelbrand.com.br/.well-known/mcp/server-card.json` | `application/json` | | Robots + Content-Signal | `https://sentinelbrand.com.br/robots.txt` | `text/plain` | --- ## Registro de Agentes (RFC 7591 — Dynamic Client Registration) ### Endpoint ``` POST https://sentinelbrand.com.br/oauth/agents/register Content-Type: application/json ``` > **Sem autenticação prévia** para criação inicial (campo `registration_endpoint_auth_methods_supported` > no well-known contém `none`). Atualizações e leitura de cliente existente exigem o `registration_access_token` > retornado na criação. ### Requisição de Registro — exemplos #### Agente autônomo (client credentials, acesso a dados de marca) ```json { "client_name": "Agente MonitoraCorp", "client_uri": "https://agente.exemplo.ai", "logo_uri": "https://agente.exemplo.ai/logo.png", "grant_types": [ "client_credentials", "refresh_token" ], "response_types": ["token"], "scope": "mentions:read sentiment:read alerts:read", "token_endpoint_auth_method": "client_secret_basic", "agent_identity_type": "did:web", "agent_identity": "did:web:agente.exemplo.ai" } ``` #### Agente em nome de usuário (authorization code + PKCE) ```json { "client_name": "ReputacaoCopilot", "client_uri": "https://copilot.exemplo.app", "redirect_uris": [ "https://copilot.exemplo.app/oauth/callback", "http://localhost:5173/oauth/callback" ], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "openid profile email mentions:read alerts:write", "code_challenge_method": "S256", "token_endpoint_auth_method": "none" } ``` ### Resposta de Registro (HTTP 201 Created) ```json { "client_id": "sb_ag_2N8fxP_example", "client_secret": "sb_sec_uMp_example_secret_value", "client_id_issued_at": 1722790000, "client_secret_expires_at": 0, "registration_access_token": "sb_reg_eyJhbGc_example_access_token", "registration_client_uri": "https://sentinelbrand.com.br/oauth/agents/client/sb_ag_2N8fxP_example", "token_endpoint_auth_method": "client_secret_basic", "agent_identity_type": "did:web", "agent_identity": "did:web:agente.exemplo.ai" } ``` --- ## Fluxos OAuth Suportados ### 1. Client Credentials (Máquina-a-Máquina, recomendado para bots) ``` POST https://sentinelbrand.com.br/oauth/token Authorization: Basic base64(client_id:client_secret) Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &scope=mentions:read sentiment:read alerts:read ``` ### 2. Authorization Code (agente em nome do usuário final) 1. Direcione o usuário para: ``` https://sentinelbrand.com.br/oauth/authorize ?response_type=code &client_id=YOUR_CLIENT_ID &redirect_uri=YOUR_REDIRECT_URI &scope=openid profile mentions:read &code_challenge=BASE64URL(SHA256(code_verifier)) &code_challenge_method=S256 ``` 2. Troque o `code` por tokens: ``` POST https://sentinelbrand.com.br/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTH_CODE &client_id=YOUR_CLIENT_ID &redirect_uri=YOUR_REDIRECT_URI &code_verifier=CODE_VERIFIER ``` ### 3. Device Authorization Flow (dispositivos sem browser) ``` POST https://sentinelbrand.com.br/oauth/device Content-Type: application/x-www-form-urlencoded client_id=YOUR_CLIENT_ID &scope=mentions:read sentiment:read ``` --- ## Escopos Disponíveis | Escopo | Descrição | |--------|-----------| | `mentions:read` | Listar / buscar menções da marca em canais digitais | | `sentiment:read` | Agregados e série histórica de análise de sentimento | | `alerts:read` | Ler alertas de crise e spikes configurados | | `alerts:write` | Criar, editar e silenciar alertas de crise | | `openid` | OpenID Connect (retorna `id_token`) | | `profile` | Nome, avatar e URL de perfil do usuário final | | `email` | Endereço de e-mail verificado do usuário final | --- ## APIs Principais (consulte `.well-known/api-catalog` para schema completo) | Recurso | Método | Escopo mínimo | |---|---|---| | `/api/v1/mentions?brand=...&since=...` | `GET` | `mentions:read` | | `/api/v1/sentiment?brand=...&period=7d` | `GET` | `sentiment:read` | | `/api/v1/alerts` | `GET` | `alerts:read` | | `/api/v1/alerts` | `POST` | `alerts:write` | | `/api/v1/clipping?brand=...&hours=24` | `GET` | `mentions:read` | | `/api/v1/crisis/active?brand=...` | `GET` | `alerts:read` | Exemplo de chamada autenticada: ```http GET https://sentinelbrand.com.br/api/v1/mentions?brand=Sentinel&since=2026-08-01 Authorization: Bearer ACCESS_TOKEN_AQUI Accept: application/json ``` --- ## Revogação ``` POST https://sentinelbrand.com.br/oauth/revoke Authorization: Basic base64(client_id:client_secret) Content-Type: application/x-www-form-urlencoded token=ACCESS_TOKEN_OU_REFRESH_TOKEN &token_type_hint=access_token ``` ## Suporte / SLA - E-mail: `agents@sentinelbrand.com.br` (SLA 24h úteis) - Limites padrão: - Client Credentials: **100 req/min** por client_id - Authorization Code: **1000 req/min** por usuário final - Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` (quando 429) ## Referências normativas - RFC 6749 — The OAuth 2.0 Authorization Framework - RFC 7591 — OAuth 2.0 Dynamic Client Registration Protocol - RFC 7636 — PKCE - RFC 8414 — OAuth 2.0 Authorization Server Metadata - RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP) - RFC 9728 — OAuth 2.0 Protected Resource Metadata - RFC 9727 — Semantic API Catalog - https://workos.com/auth-md — auth.md specification