Kimlik doğrulama

Kendini tanıtan kök uç nokta dışındaki her istekte tek bir başlık.

Authorization: Bearer <your api key>

Token'lar profil sayfanızda oluşturulur: hesap başına en fazla on tane. Her biri ayrı ayrı iptal edilebilir; böylece sızan bir token diğerlerine dokunmadan silinebilir. Ücretli bir plan gerekir: plan yoksa / ve /v1/account dışındaki her uç nokta 403 plan_required yanıtını verir.

Bir uygulama da OAuth 2.1 üzerinden sizin için token alabilir: giriş yaparsınız, uygulamanın ne istediğini görürsünüz ve “İzin ver” düğmesine basarsınız. Bu token aynı başlıkta gönderilir ve aynı şekilde çalışır.

Neden ?key= değil

URL'nin sorgu dizesindeki bir anahtar, sizin koymadığınız yerlere ulaşır: web sunucusu erişim günlükleri, tarayıcı geçmişi, proxy günlükleri ve yanıtın bağlantı verdiği her şeyin Referer başlığı. Bu nedenle API bunu kabul etmez ve nedenini belirterek 401 missing_key yanıtını verir.

Ana sitedeki eski ?export= URL'leri ise ?key= parametresini hâlâ kabul eder; çünkü yıllar önce yazılmış betikler buna dayanır ve kaldırılması onları bozar. Bunun geçerli olduğu tek yer orasıdır; bkz. eski dışa aktarma URL'leri.

Anahtarın çalıştığını kontrol etme

/v1/account en ucuz çağrıdır: kota harcamaz ve planı olmayan bir hesapta bile çalışır. Böylece hem “bu anahtar geçerli mi” hem de “neye hakkım var” sorusunu yanıtlar.

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

Neler ters gidebilir

401 yanıtı ayrıca bir WWW-Authenticate: Bearer başlığı da taşır; böylece kimlik doğrulamayı genel yöntemlerle işleyen HTTP istemcileri doğru davranır.

Uygulamalar için OAuth 2.1

Başkaları adına çalışan bir uygulama (bir asistan, bir entegrasyon, barındırılan bir hizmet) bu kişilerin her birinden token kopyalamasını istememelidir. Bunun yerine onları PublicWWW sitesine yönlendirir: giriş yaparlar, uygulamayı onaylarlar ve uygulama kendine ait bir token alır. Bu token diğerleri gibi Authorization: Bearer olarak gönderilir ve hesabın planı, kotası ve hız sınırı dahilinde tüm API'ye ve https://api.publicwww.com/mcp adresindeki MCP sunucusuna erişim sağlar.

Uygulamanın tanıtılması

İstemci kaydı yoktur. client_id, uygulamanın yayımladığı küçük bir JSON belgesinin https URL'sidir; bu belgeye istemci meta veri belgesi denir. PublicWWW bu belgeyi biri her bağlandığında yeniden okur; böylece ad ve dönüş adresleri her zaman günceldir ve onay veren kişi bunları hangi sunucunun yayımladığını görür.

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

• Belgedeki client_id, belgenin sunulduğu URL ile birebir aynı olmalıdır. Belge https üzerinden, yol içeren bir URL'den, yönlendirmeler izlenmeden alınır; 5 saniye içinde yanıt vermeli ve boyutu 64 KB altında kalmalıdır.
• redirect_uris https adresleri olmalıdır; kişinin kendi bilgisayarında çalışan bir uygulama içinse 127.0.0.1, localhost ya da [::1] üzerinde http de olabilir ve orada her port eşleşir. myapp:// gibi özel şemalar kabul edilmez.
• Her uygulama açık istemcidir (public client): belge hangi token_endpoint_auth_method değerini belirtirse belirtsin, token isteği gizli anahtar taşımaz. Yetkilendirme kodu bunun yerine PKCE ile korunur.

Akış

PKCE ile yetkilendirme kodu akışı; yöntem olarak yalnızca S256 desteklenir. Kişiyi yetkilendirme uç noktasına gönderin:

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>

Kişi henüz giriş yapmamışsa e-postayla gönderilen tek kullanımlık bir kodla giriş yapar; uygulamanın adını, belgesinin bulunduğu sunucuyu ve nereye döneceğini görür, ardından “İzin ver” ya da “İptal” düğmesine basar. redirect_uri adresine code, sizin state değeriniz ve iss=https://publicwww.com (RFC 9207) gelir. Kod on dakika geçerlidir ve yalnızca bir kez kullanılabilir. Kodu bir token'la takas edin:

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 parametresi atlanabilir: yalnızca bir kapsam vardır, mcp, ve tüm API'yi içerir. resource (RFC 8707) parametresi de atlanabilir; gönderilirse değeri https://api.publicwww.com/mcp ya da https://api.publicwww.com olur.

Token ne kadar geçerli

İptal edilene kadar: süre sonu ve yenileme token'ı (refresh token) yoktur. Bugün çalışan bir entegrasyon, kimse dokunmadan yarın da çalışır. Bir token yalnızca bilerek iptal edilir: kişi profil sayfasında uygulamanın bağlantısını keser, uygulama token'ı kendisi iptal eder ya da hesap silinir.

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

İptal uç noktası, token var olsun ya da olmasın her zaman 200 yanıtını verir.

OAuth hataları

Hata sayfası dışındaki yetkilendirme hataları redirect_uri adresine error, error_description, state ve iss olarak döner; token hataları ise aynı iki alanı JSON içinde taşıyan bir 400 yanıtıdır.