claritos
deenru

OAuth 2.1

Для приложений, действующих от имени пользователя (Zapier, n8n, чат-коннекторы): код авторизации с PKCE, refresh-токены, согласие с выбором организации. Для сервер-сервер API-ключ остаётся более простым путём.

Когда OAuth, когда ключи

API-ключи (capi_…) принадлежат организации и подходят для скриптов и серверов. OAuth-токены принадлежат пользователю, который в окне согласия открывает одну организацию — так конечные пользователи подключают свою организацию claritos к стороннему приложению без копирования ключей. Оба пути используют те же scopes и конечные точки.

Код авторизации + PKCE

Клиент направляет пользователя на авторизацию (PKCE обязателен, S256), после согласия получает код на своём redirect-URI и обменивает его на конечной точке токена на токен доступа (1 час) и refresh-токен (30 дней). Конфиденциальные клиенты передают client_secret; публичные — только code_verifier.

http
GET https://www.claritos.io/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20offline_access%20contacts:read%20invoices:write
  &state=RANDOM
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
curl
curl -X POST https://www.claritos.io/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_CALLBACK \
  -d redirect_uri=https://app.example.com/callback \
  -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET \
  -d code_verifier=CODE_VERIFIER
json
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "openid offline_access contacts:read invoices:write"
}

Согласие с выбором организации

Пользователь видит клиента и запрошенные разрешения и выбирает организацию, к которой относится доступ. Ровно одна на подключение; разрешения действуют в пределах роли пользователя в организации (членство проверяется при каждом вызове). Scopes клиентских данных дополнительно требуют включения организации. Начиная с 1.26.0 пользователь может снимать отдельные разрешения в согласии; доступ действует только для выбранных scopes, scopes клиентских данных по умолчанию сняты. Пользователи видят свои разрешения в профиле в разделе «Подключённые приложения» и могут отозвать их в любой момент.

Вызов API

Токен доступа передаётся как Bearer-токен, как и ключ. GET /me показывает организацию, scopes и лимиты токена.

curl
curl https://www.claritos.io/api/v1/me -H "Authorization: Bearer ACCESS_TOKEN"

Обновление токенов

Когда токен доступа истекает, конечная точка токена с grant_type=refresh_token возвращает новую пару. Refresh-токены ротируются.

curl
curl -X POST https://www.claritos.io/api/auth/oauth2/token \
  -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET

Discovery

Метаданные по RFC 8414 (сервер авторизации) и RFC 9728 (защищённый ресурс) лежат в корне; конфигурация OpenID дополнительно по пути auth. Клиентам с поддержкой discovery (MCP-коннекторы) достаточно базового URL.

http
GET https://www.claritos.io/.well-known/oauth-authorization-server
GET https://www.claritos.io/.well-known/oauth-protected-resource
GET https://www.claritos.io/api/auth/.well-known/openid-configuration

Динамическая регистрация клиентов

Клиенты могут регистрироваться сами (RFC 7591) — так подключаются claude.ai, ChatGPT и другие MCP-клиенты без ручной настройки. Зарегистрированные клиенты отображаются в системном разделе, где их можно отключить.

curl
curl -X POST https://www.claritos.io/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My MCP client", "redirect_uris": ["https://client.example.com/cb"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code","refresh_token"] }'

Zapier, n8n, Make

Создайте клиента в системном разделе (укажите redirect-URI платформы), сохраните там client_id/client_secret, URL авторизации /api/auth/oauth2/authorize, URL токена /api/auth/oauth2/token, scopes по необходимости (например contacts:write invoices:read). Включите PKCE, если платформа это поддерживает. Настройка по платформам — см. руководство «Webhooks» → Платформы.