OAuth 2.1 для API SpeakNotes

Обнаружение

Оба документа метаданных являются общедоступными. Клиенты MCP находят их автоматически на основе ответа 401, возвращаемого API.

# 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

   Регистрация клиента

   Отправьте POST-запрос на эндпоинт регистрации с вашими URI перенаправления. Публичные клиенты используют PKCE и не получают секрет; конфиденциальные клиенты получают его. Принимаются https, loopback 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

   Отправка пользователя для авторизации

   Откройте эндпоинт авторизации с вашим идентификатором клиента, URI перенаправления, областями доступа (scopes), состоянием и S256 code challenge. Пользователь входит в систему, видит, какие именно области доступа вы запросили, и одобряет или отклоняет их.

   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

   Обмен кода

   Отправьте POST-запрос с кодом и верификатором кода на эндпоинт токенов. Коды являются одноразовыми и истекают через минуту; повторное использование кода приводит к отзыву токенов, которые он создал.

   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

   Обновление

   Токены доступа действуют один час. Токены обновления меняются при каждом использовании, и предъявление отозванного токена аннулирует всё разрешение, что предотвращает использование украденного токена.

   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_..."}'