SpeakNotes API için OAuth 2.1

Keşif

Her iki meta veri belgesi de herkese açıktır. MCP istemcileri, API'nin döndürdüğü 401 sınamasından bunları otomatik olarak bulur.

# Authorization server metadata (RFC 8414)
curl https://speaknotes.io/.well-known/oauth-authorization-server

# Protected resource metadata (RFC 9728)
curl https://api.speaknotes.io/.well-known/oauth-protected-resource

Akış

1. 1

   Bir istemci kaydedin

   Yönlendirme URI'lerinizle birlikte kayıt uç noktasına POST isteği gönderin. Genel istemciler PKCE kullanır ve gizli anahtar almaz; gizli istemciler ise bir anahtar alır. https, loopback http ve özel uygulama şemalarının tümü kabul edilir.

   curl -X POST https://api.speaknotes.io/oauth/register \
     -H "Content-Type: application/json" \
     -d '{
       "client_name": "Your app",
       "redirect_uris": ["https://your.app/callback"],
       "token_endpoint_auth_method": "none",
       "scope": "notes:read notes:write summaries:write"
     }'

2. 2

   Kullanıcıyı yetkilendirmeye yönlendirin

   Yetkilendirme uç noktasını istemci kimliğiniz, yönlendirme URI'niz, kapsamlar, durum ve bir S256 kod sınaması ile açın. Kullanıcı giriş yapar, tam olarak hangi kapsamları istediğinizi görür ve onaylar veya reddeder.

   https://speaknotes.io/oauth/authorize
     ?client_id=sn_client_...
     &redirect_uri=https://your.app/callback
     &response_type=code
     &scope=notes:read%20summaries:write
     &state=RANDOM
     &code_challenge=BASE64URL_SHA256_OF_VERIFIER
     &code_challenge_method=S256

3. 3

   Kodu değiştirin

   Kodu ve kod doğrulayıcınızı belirteç (token) uç noktasına POST edin. Kodlar tek kullanımlıktır ve bir dakika içinde sona erer; bir kodu tekrar kullanmak, ürettiği belirteçleri iptal eder.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "client_id": "sn_client_...",
       "code": "...",
       "redirect_uri": "https://your.app/callback",
       "code_verifier": "..."
     }'

4. 4

   Yenileme

   Erişim belirteçleri bir saat geçerlidir. Yenileme belirteçleri her kullanımda döner ve iptal edilmiş bir belirtecin sunulması tüm yetkiyi düşürür; bu, çalınan bir belirtecin işe yaramaz hale gelmesini sağlar.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "refresh_token",
       "client_id": "sn_client_...",
       "refresh_token": "sn_rt_..."
     }'

access_token: 1h · refresh_token: 60d, rotating · code: 60s, single use

Kapsam talebi

Sadece ihtiyacınız olan en az kapsamı isteyin. Bir yenileme kapsamı daraltabilir ancak asla genişletemez; kullanıcılar uygulamaları ayarlarından görebilir ve iptal edebilirler.

İptal

Belirteçlerden herhangi birini iptal uç noktasına POST edin. Birini iptal etmek ikiliyi geçersiz kılar. RFC 7009 uyarınca, hiç var olmamış bir belirteci iptal etmek yine de başarılı sayılır.

curl -X POST https://api.speaknotes.io/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"client_id": "sn_client_...", "token": "sn_rt_..."}'