Документация для разработчиков ZIPPY

Базовый URL авторизации и токенов: https://zippy-chat.ru. Идентификатор пользователя в userinfo — поле sub (числовой id, как в продакшене).

С чего начать (5 минут)

1. Войдите на .dev тем же аккаунтом, что и на основном сайте (или зарегистрируйтесь — вас вернёт параметр next).
2. Откройте Ключи и создайте приложение: только HTTPS redirect_uri, секрет сохраните сразу.
3. Перенаправьте пользователя на /oauth/authorize, обменяйте code на /oauth/token, затем дерните /oauth/userinfo.

Вход на лабораторию и сессия

На *.zippy-chat.ru cookie входа общая для поддоменов (см. app.session_cookie_domain в конфиге). Лаборатория читает сессию из БД и при необходимости выдаёт служебный Bearer для вызова /developer/api/v1/apps. Сторонний сайт на другом домене этой cookie не видит — там только полный OAuth-поток.

1. Регистрация OAuth-приложения (UI)

Раздел /keys: имя от 2 символов, redirect строго по HTTPS. Один и тот же redirect должен участвовать и в запросе authorize, и в теле /oauth/token.

2. Authorization Code и области доступа (scope)

В URL авторизации добавьте пробел‑разделённый список scope. Если не указать — используются openid profile email. Пароль учётной записи через OAuth никогда не передаётся — так устроены безопасные потоки; для связки Colime/Zippy вход на стороне Zippy остаётся отдельным шагом, а приложение получает только выбранные данные.

Пример полного набора для федерации с другой соцсетью (например Colime): добавьте в authorize все нужные области.

GET https://zippy-chat.ru/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://your.site/oauth/callback&state=RANDOM&scope=openid%20profile%20email%20posts.read%20messages.read

POST https://zippy-chat.ru/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=CODE&redirect_uri=ТОТ ЖЕ URL-КОДИРОВАНИЕМ&client_id=…&client_secret=…

Ответ: JSON с access_token, token_type: Bearer, expires_in, поле scope — выданные области (может включать базовые openid profile email).

3. Userinfo (/oauth/userinfo)

GET https://zippy-chat.ru/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Поля зависят от scope выданного токена: обычно sub; при profile — name, preferred_username, nickname, picture, birthdate, bio, banner, registered_at; при email — email, email_verified.

4. Расширенный профиль и данные для федерации (Colime)

GET https://zippy-chat.ru/oauth/api/v1/me
Authorization: Bearer ACCESS_TOKEN

Нужен scope profile. Ответ: sub, scopes, объект profile с полями профиля (email попадает туда только если в токене есть email).

GET https://zippy-chat.ru/oauth/api/v1/posts?limit=50
Authorization: Bearer ACCESS_TOKEN

Нужен posts.read. Поля постов включают media_url (абсолютный URL) при наличии вложения.

GET https://zippy-chat.ru/oauth/api/v1/messages?limit=60
Authorization: Bearer ACCESS_TOKEN

Нужен messages.read. Последние сообщения из личных диалогов: peer_user_id, текст, медиа.

5. Developer API — список и создание приложений

GET https://zippy-chat.ru/developer/api/v1/apps
Authorization: Bearer ACCESS_TOKEN

POST https://zippy-chat.ru/developer/api/v1/apps
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{"name":"Мой сайт","redirect_uri":"https://example.com/callback"}

Создание: в ответе один раз приходит client_secret. Ошибки — JSON {"error":"…"}, коды 400/401/429.

6. Эндпоинты только для .dev (тот же браузер)

Ошибки и отладка

• invalid_grant — неверный или повторно использованный code, несовпадение redirect_uri.
• invalid_client — неверный client_id / secret.
• 401 userinfo — истёкший или не тот токен.
• Внутренний callback лаборатории на проде: https://zippy-chat.ru/oauth/dev-portal/callback (в app.oauth_dev_portal.redirect_uris).

Безопасность

• Secret только на сервере; в мобильных клиентах — PKCE вместо секрета в приложении.
• Только HTTPS в продакшене для redirect и API.
• Не логируйте code и access_token.

Больше готовых запросов — сниппеты и плейбук.