Autenticación

Un solo encabezado, en todas las solicitudes excepto en el índice que se describe a sí mismo.

Authorization: Bearer <your api key>

Los tokens se crean en tu página de perfil: hasta diez por cuenta, y cada uno se puede revocar por separado, así que si uno se filtra se puede eliminar sin tocar los demás. Se necesita un plan de pago: sin él, todos los endpoints excepto / y /v1/account responden 403 plan_required.

Una aplicación también puede obtener un token por ti mediante OAuth 2.1: inicias sesión, ves qué pide y haces clic en «Permitir». Su token va en el mismo encabezado y funciona igual.

Por qué no ?key=

Una clave en la cadena de consulta acaba en sitios donde no la pusiste: los registros de acceso del servidor web, el historial del navegador, los registros de los proxies y el encabezado Referer de cualquier recurso al que enlace la respuesta. Por eso la API no la acepta y responde 401 missing_key indicándolo.

Las antiguas URL con ?export= del sitio principal todavía aceptan ?key=, porque hay scripts escritos hace años que dependen de ello y quitarlo los rompería. Es el único lugar donde se mantiene; consulta las antiguas URL de exportación.

Comprobar que una clave funciona

/v1/account es la llamada más barata: no consume cuota y funciona incluso en una cuenta sin plan, así que responde a la vez a «¿esta clave es válida?» y a «¿a qué tengo derecho?».

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
  }
}

Qué puede fallar

Un 401 también incluye el encabezado WWW-Authenticate: Bearer, para que los clientes HTTP que gestionan la autenticación de forma genérica se comporten correctamente.

OAuth 2.1 para aplicaciones

Una aplicación que trabaja en nombre de otras personas (un asistente, una integración, un servicio alojado) no debería pedir a cada una que copie un token. En su lugar, las envía a PublicWWW: inician sesión, aprueban la aplicación y esta recibe su propio token. Ese token se envía como Authorization: Bearer, igual que cualquier otro, y da acceso a toda la API y al servidor MCP en https://api.publicwww.com/mcp, con el plan, la cuota y el límite de frecuencia de la cuenta.

Identificar la aplicación

No hay registro de clientes. El client_id es la URL https de un pequeño documento JSON que publica la aplicación: un documento de metadatos del cliente. PublicWWW lo lee cada vez que alguien se conecta, así que el nombre y las direcciones de retorno siempre están al día, y quien aprueba ve qué host los ha publicado.

{
  "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"
}

• El client_id dentro del documento debe ser exactamente la URL desde la que se sirve. El documento se obtiene por https, desde una URL con ruta, sin seguir redirecciones; debe responder en menos de 5 segundos y ocupar menos de 64 KB.
• Los redirect_uris son direcciones https, o http en 127.0.0.1, localhost o [::1] para una aplicación que se ejecuta en el propio equipo de la persona; en ese caso vale cualquier puerto. No se aceptan esquemas personalizados como myapp://.
• Todas las aplicaciones son clientes públicos: la solicitud de token no lleva ningún secreto, sea cual sea el token_endpoint_auth_method que indique el documento. En su lugar, el código de autorización se protege con PKCE.

El flujo

Código de autorización con PKCE; S256 es el único método. Envía a la persona al endpoint de autorización:

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>

Si aún no ha iniciado sesión, lo hace con un código de un solo uso que recibe por correo electrónico; ve el nombre de la aplicación, el host de su documento y adónde volverá, y hace clic en «Permitir» o «Cancelar». En el redirect_uri se reciben code, tu state e iss=https://publicwww.com (RFC 9207). Un código es válido durante diez minutos y funciona una sola vez. Intercámbialo:

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 se puede omitir: hay un único ámbito, mcp, y abarca toda la API. resource (RFC 8707) también se puede omitir; si se envía, es https://api.publicwww.com/mcp o https://api.publicwww.com.

Cuánto dura un token

Hasta que se revoca: no expira y no hay token de actualización. Una integración que funciona hoy sigue funcionando mañana sin que nadie la toque. Un token solo se revoca de forma intencionada: la persona desconecta la aplicación en su página de perfil, la propia aplicación lo revoca o se elimina la cuenta.

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

El endpoint de revocación siempre responde 200, exista o no el token.

Errores de OAuth

Los errores de autorización, salvo la página de error, vuelven al redirect_uri como error, error_description, state e iss; los errores de token son un 400 con los mismos dos campos en JSON.