Authentifizierung

Ein Header, bei jeder Anfrage außer dem selbstbeschreibenden Index.

Authorization: Bearer <your api key>

Token werden auf Ihrer Profilseite erstellt - bis zu zehn pro Konto, jedes einzeln widerrufbar, sodass ein kompromittiertes Token gelöscht werden kann, ohne die anderen zu berühren. Ein kostenpflichtiger Tarif ist erforderlich: Ohne ihn antwortet jeder Endpunkt außer / und /v1/account mit 403 plan_required.

Eine Anwendung kann auch über OAuth 2.1 ein Token für Sie beziehen: Sie melden sich an, sehen, was die Anwendung anfordert, und klicken auf „Zulassen“. Ihr Token wird im selben Header gesendet und funktioniert genauso.

Warum nicht ?key=

Ein Schlüssel im Query-String landet an Orten, an die Sie ihn nicht gelegt haben: in Zugriffsprotokollen von Webservern, im Browserverlauf, in Proxy-Protokollen und im Referer-Header von allem, worauf die Antwort verlinkt. Die API akzeptiert ihn daher nicht und antwortet mit 401 missing_key samt entsprechendem Hinweis.

Die alten ?export=-URLs auf der Hauptsite akzeptieren ?key= weiterhin, weil vor Jahren geschriebene Skripte darauf angewiesen sind und eine Abschaffung sie zum Absturz bringen würde. Das ist der einzige Ort, an dem es ihn noch gibt - siehe Die alten Export-URLs.

Prüfen, ob ein Schlüssel funktioniert

/v1/account ist der günstigste Aufruf: Er verbraucht kein Kontingent und funktioniert sogar bei einem Konto ohne Tarif. Er beantwortet also sowohl „Ist dieser Schlüssel gültig?“ als auch „Worauf habe ich Anspruch?“.

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

Was schiefgehen kann

Ein 401 enthält außerdem einen WWW-Authenticate: Bearer-Header, sodass HTTP-Clients mit generischer Authentifizierungslogik sich sinnvoll verhalten.

OAuth 2.1 für Anwendungen

Eine Anwendung, die im Auftrag anderer Personen arbeitet - ein Assistent, eine Integration, ein gehosteter Dienst -, sollte nicht jede Person bitten, ein Token zu kopieren. Stattdessen schickt sie sie zu PublicWWW: Dort melden sie sich an, genehmigen die Anwendung, und diese erhält ein eigenes Token. Dieses Token wird wie jedes andere als Authorization: Bearer gesendet und öffnet die gesamte API sowie den MCP-Server unter https://api.publicwww.com/mcp - im Rahmen von Tarif, Kontingent und Ratenlimit des Kontos.

Die Anwendung identifizieren

Eine Client-Registrierung gibt es nicht. Die client_id ist die https-URL eines kleinen JSON-Dokuments, das die Anwendung veröffentlicht - eines Client-Metadatendokuments. PublicWWW liest es bei jeder Verbindung, sodass Name und Rücksprungadressen immer aktuell sind und die genehmigende Person sieht, welcher Host sie veröffentlicht hat.

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

• client_id im Dokument muss exakt der URL entsprechen, unter der es ausgeliefert wird. Das Dokument wird per https von einer URL mit Pfad abgerufen, ohne Weiterleitungen zu folgen; es muss innerhalb von 5 Sekunden antworten und kleiner als 64 KB sein.
• redirect_uris sind https-Adressen oder http auf 127.0.0.1, localhost bzw. [::1] für eine Anwendung, die auf dem eigenen Computer der Person läuft - dort passt jeder Port. Eigene Schemata wie myapp:// werden nicht akzeptiert.
• Jede Anwendung ist ein öffentlicher Client: Die Token-Anfrage enthält kein Secret, gleich welche token_endpoint_auth_method das Dokument angibt. Der Autorisierungscode wird stattdessen durch PKCE geschützt.

Der Ablauf

Authorization Code mit PKCE; S256 ist die einzige Methode. Leiten Sie die Person zum Autorisierungs-Endpunkt:

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>

Falls noch nicht geschehen, meldet sie sich mit einem per E-Mail gesendeten Einmalcode an, sieht den Namen der Anwendung, den Host ihres Dokuments und wohin sie zurückkehrt, und klickt auf „Zulassen“ oder „Abbrechen“. Zurück an der redirect_uri kommen code, Ihr state und iss=https://publicwww.com (RFC 9207). Ein Code ist zehn Minuten gültig und funktioniert nur einmal. Tauschen Sie ihn ein:

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 kann entfallen: Es gibt nur einen Scope, mcp, und er umfasst die gesamte API. Auch resource (RFC 8707) kann entfallen; wird es gesendet, lautet es https://api.publicwww.com/mcp oder https://api.publicwww.com.

Wie lange ein Token gilt

Bis es widerrufen wird - es gibt kein Ablaufdatum und kein Refresh-Token. Eine Integration, die heute funktioniert, funktioniert auch morgen, ohne dass jemand sie anfassen muss. Ein Token wird nur absichtlich widerrufen: Die Person trennt die Anwendung auf ihrer Profilseite, die Anwendung widerruft es selbst, oder das Konto wird gelöscht.

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

Der Widerrufs-Endpunkt antwortet immer mit 200, unabhängig davon, ob das Token existiert hat.

OAuth-Fehler

Autorisierungsfehler außer der Fehlerseite kommen an der redirect_uri als error, error_description, state und iss zurück; Token-Fehler sind ein 400 mit denselben zwei Feldern im JSON.