Autenticação

Um cabeçalho, em todas as requisições, exceto no índice autodescritivo.

Authorization: Bearer <your api key>

Os tokens são gerados na sua página de perfil: até dez por conta, cada um revogável separadamente, para que um token vazado possa ser excluído sem afetar os outros. É preciso ter um plano pago: sem ele, todos os endpoints, exceto / e /v1/account, respondem 403 plan_required.

Um aplicativo também pode obter um token para você via OAuth 2.1: você entra, vê o que ele está pedindo e clica em Permitir. O token dele vai no mesmo cabeçalho e funciona da mesma forma.

Por que não ?key=

Uma chave na query string acaba em lugares onde você não a colocou: logs de acesso do servidor web, histórico do navegador, logs de proxy e o cabeçalho Referer de qualquer coisa para a qual a resposta tenha links. Por isso a API não a aceita e responde 401 missing_key, explicando o motivo.

As URLs antigas com ?export= no site principal ainda aceitam ?key=, porque scripts escritos há anos dependem disso e retirar esse recurso os quebraria. Esse é o único lugar em que ele ainda existe; veja as URLs de exportação antigas.

Como verificar se uma chave funciona

/v1/account é a chamada mais barata: não consome cota e funciona até em uma conta sem plano, então responde tanto “esta chave é válida?” quanto “a que eu tenho direito?”.

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

O que pode dar errado

Uma resposta 401 também traz o cabeçalho WWW-Authenticate: Bearer, para que clientes HTTP que tratam a autenticação de forma genérica se comportem corretamente.

OAuth 2.1 para aplicativos

Um aplicativo que age em nome de outras pessoas (um assistente, uma integração, um serviço hospedado) não deveria pedir a cada uma delas que copie um token. Em vez disso, ele as envia ao PublicWWW: elas entram, aprovam o aplicativo, e ele recebe um token próprio. Esse token é enviado como Authorization: Bearer, como qualquer outro, e dá acesso a toda a API e ao servidor MCP em https://api.publicwww.com/mcp, dentro do plano, da cota e do limite de requisições da conta.

Como o aplicativo é identificado

Não há registro de clientes. O client_id é a URL https de um pequeno documento JSON que o aplicativo publica: um documento de metadados do cliente. O PublicWWW o lê sempre que alguém se conecta, então o nome e os endereços de retorno estão sempre atualizados, e quem aprova vê qual host os publicou.

{
  "client_id": "https://app.example.com/oauth/client.json",
  "client_name": "Example App",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

• O client_id dentro do documento deve ser exatamente a URL da qual ele é servido. O documento é obtido via https, a partir de uma URL com caminho, sem seguir redirecionamentos; ele precisa responder em até 5 segundos e ter menos de 64 KB.
• Os redirect_uris são endereços https, ou http em 127.0.0.1, localhost ou [::1] para um aplicativo rodando no próprio computador da pessoa; nesse caso, qualquer porta é aceita. Esquemas personalizados como myapp:// não são aceitos.
• Todo aplicativo é um cliente público: a requisição de token não leva segredo, seja qual for o token_endpoint_auth_method indicado no documento. Em vez disso, o código de autorização é protegido por PKCE.

O fluxo

Authorization code com PKCE; S256 é o único método. Envie a pessoa ao endpoint de autorização:

https://publicwww.com/oauth/authorize
    ?response_type=code
    &client_id=https%3A%2F%2Fapp.example.com%2Foauth%2Fclient.json
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
    &code_challenge=<BASE64URL(SHA-256(code_verifier))>
    &code_challenge_method=S256
    &state=<random>

Se ainda não estiver logada, a pessoa entra com um código de uso único enviado por e-mail, vê o nome do aplicativo, o host do documento dele e para onde vai voltar, e clica em Permitir ou Cancelar. De volta ao redirect_uri chegam code, o seu state e iss=https://publicwww.com (RFC 9207). O código vale por dez minutos e funciona uma única vez. Troque-o:

curl https://publicwww.com/oauth/token \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d code_verifier="$VERIFIER" \
     -d client_id=https://app.example.com/oauth/client.json \
     -d redirect_uri=https://app.example.com/oauth/callback

{ "access_token": "<token>", "token_type": "Bearer", "scope": "mcp" }

scope pode ser omitido: há um único escopo, mcp, e ele cobre toda a API. resource (RFC 8707) também pode ser omitido; se enviado, deve ser https://api.publicwww.com/mcp ou https://api.publicwww.com.

Quanto tempo um token dura

Até ser revogado: não há expiração nem refresh token. Uma integração que funciona hoje continua funcionando amanhã sem que ninguém precise mexer nela. Um token só é revogado de propósito: quando a pessoa desconecta o aplicativo na sua página de perfil, quando o próprio aplicativo o revoga ou quando a conta é excluída.

curl https://publicwww.com/oauth/revoke \
     -d token="$TOKEN" \
     -d client_id=https://app.example.com/oauth/client.json

O endpoint de revogação sempre responde 200, quer o token existisse ou não.

Erros de OAuth

Os erros de autorização, exceto a página de erro, voltam para o redirect_uri como error, error_description, state e iss; os erros de token são uma resposta 400 com os mesmos dois campos em JSON.