SpeakNotes API를 위한 OAuth 2.1

디스커버리

두 메타데이터 문서 모두 공개되어 있습니다. MCP 클라이언트는 API가 반환하는 401 챌린지로부터 이를 자동으로 찾습니다.

# 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

플로우

1. 1

   클라이언트 등록

   리다이렉트 URI와 함께 등록 엔드포인트로 POST 요청을 보냅니다. 퍼블릭 클라이언트는 PKCE를 사용하며 시크릿을 받지 않지만, 컨피덴셜 클라이언트는 시크릿을 받습니다. https, 루프백 http, 커스텀 앱 스킴 모두 허용됩니다.

   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

   사용자 인증 요청

   클라이언트 ID, 리다이렉트 URI, 스코프, 상태 및 S256 코드 챌린지를 사용하여 인증 엔드포인트를 엽니다. 사용자는 로그인 후 요청한 스코프를 정확히 확인하고 승인하거나 거부할 수 있습니다.

   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

   코드 교환

   코드와 코드 검증기(code verifier)를 토큰 엔드포인트로 POST 요청합니다. 코드는 일회용이며 1분 내에 만료됩니다. 코드를 재사용하면 해당 코드로 생성된 토큰이 취소됩니다.

   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

   새로 고침

   액세스 토큰은 1시간 동안 유효합니다. 리프레시 토큰은 사용할 때마다 교체되며, 취소된 토큰을 제시하면 전체 권한이 삭제됩니다. 이는 도난당한 토큰이 악용되는 것을 방지합니다.

   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

스코프 요청

필요한 최소한의 권한만 요청하세요. 새로 고침 시 스코프를 좁힐 수는 있지만 넓힐 수는 없으며, 사용자는 설정에서 언제든지 앱을 확인하고 권한을 취소할 수 있습니다.

취소

토큰 중 하나를 취소 엔드포인트로 POST 요청합니다. 둘 중 하나를 취소하면 쌍으로 된 토큰이 모두 무효화됩니다. RFC 7009에 따라 존재하지 않는 토큰을 취소하는 것도 성공으로 간주됩니다.

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