IZEK API — документация авторизации

1. Общая информация

IZEK API OAuth — это вход на внешние сайты через аккаунт IZEK. Работает по стандартной схеме OAuth 2.0 Authorization Code: внешний сайт перенаправляет пользователя на IZEK, пользователь подтверждает доступ, после чего сайт получает временный код, меняет его на access token и запрашивает профиль.

2. Создание API-приложения

Перед интеграцией создайте приложение в панели управления. После создания вы получите Client ID и Client Secret. Секретный ключ показывается один раз — сохраните его сразу.

3. Схема авторизации

1. Пользователь нажимает кнопку «Войти через IZEK» на внешнем сайте.
2. Внешний сайт перенаправляет пользователя на /api/oauth/authorize.
3. Пользователь входит в аккаунт IZEK и подтверждает доступ.
4. IZEK возвращает пользователя на redirect_uri с параметром code.
5. Внешний сайт отправляет code на /api/oauth/token и получает access_token.
6. Внешний сайт запрашивает /api/userinfo с заголовком Authorization: Bearer ACCESS_TOKEN.

4. Быстрый старт

Минимальная ссылка для кнопки входа:

<a href="https://izek.ru/api/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fsite.ru%2Fauth%2Fizek%2Fcallback&scope=profile%20email&state=RANDOM_STATE">
  Войти через IZEK
</a>

state должен быть случайной строкой, сохранённой в сессии внешнего сайта. После возврата сравните полученный state с сохранённым.

5. Endpoint авторизации

GET /api/oauth/authorize

GET https://izek.ru/api/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fsite.ru%2Fauth%2Fizek%2Fcallback&scope=profile%20email&state=RANDOM_STATE

После подтверждения IZEK перенаправит пользователя обратно:

https://site.ru/auth/izek/callback?code=AUTH_CODE&state=RANDOM_STATE

6. Получение access token

POST /api/oauth/token

Запрос выполняется сервером внешнего сайта. Не отправляйте client_secret из браузера.

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

grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https%3A%2F%2Fsite.ru%2Fauth%2Fizek%2Fcallback

Успешный ответ:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile email"
}

• authorization code живёт 5 минут и используется только один раз.
• access_token живёт 1 час.
• Если redirect_uri при обмене отличается от исходного, будет ошибка.

7. Получение профиля пользователя

GET /api/userinfo

GET https://izek.ru/api/userinfo
Authorization: Bearer ACCESS_TOKEN

Пример ответа:

{
  "id": 15,
  "email": "user@example.com",
  "username": "user",
  "name": "Имя пользователя",
  "avatar": "https://izek.ru/uploads/avatars/user_256x256.jpg",
  "avatar_url": "https://izek.ru/uploads/avatars/user_256x256.jpg",
  "avatar_small": "https://izek.ru/uploads/avatars/user_64x64.jpg",
  "avatar_medium": "https://izek.ru/uploads/avatars/user_128x128.jpg",
  "avatar_large": "https://izek.ru/uploads/avatars/user_256x256.jpg",
  "avatar_original": "https://izek.ru/uploads/avatars/user.jpg",
  "avatar_has_custom": true,
  "profile_url": "https://izek.ru/"
}

8. Готовые интеграции

Для популярных CMS и фреймворков можно использовать готовые модули авторизации через аккаунт IZEK. Это ускоряет подключение OAuth и уменьшает риск ошибок при обработке code, access_token и userinfo.

Быстрый старт для InstantCMS

1. Скачайте архив компонента instantcms_izekauth_1.0.0.zip.
2. Установите компонент через панель управления InstantCMS.
3. На IZEK откройте Панель управления → API-приложения и создайте новое приложение.
4. В Redirect URI укажите callback сайта: https://ваш-сайт.ru/izekauth/callback.
5. Скопируйте Client ID и Client Secret в настройки компонента IZEK Auth.
6. Сохраните настройки и проверьте вход через кнопку «Войти через IZEK».

9. Примеры интеграции

PHP: обмен code на token

$post = http_build_query([
    'grant_type'    => 'authorization_code',
    'code'          => $_GET['code'],
    'client_id'     => 'CLIENT_ID',
    'client_secret' => 'CLIENT_SECRET',
    'redirect_uri'  => 'https://site.ru/auth/izek/callback',
]);

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
        'content' => $post,
        'timeout' => 10,
    ]
]);

$response = file_get_contents('https://izek.ru/api/oauth/token', false, $context);
$token = json_decode($response, true);

PHP: получение userinfo

$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => 'Authorization: Bearer ' . $token['access_token'] . "\r\n",
        'timeout' => 10,
    ]
]);

$response = file_get_contents('https://izek.ru/api/userinfo', false, $context);
$user = json_decode($response, true);

PHP: сохранение аватара на стороне сайта

$avatarUrl = $user['avatar_url'] ?? $user['avatar'] ?? '';

if ($avatarUrl) {
    // Можно сохранить URL в профиль пользователя
    // или скачать файл на свой сервер, если это нужно вашей CMS.
    $avatarBinary = file_get_contents($avatarUrl);
    file_put_contents(__DIR__ . '/uploads/izek-avatar-' . (int)$user['id'] . '.jpg', $avatarBinary);
}

JavaScript / Node.js

const params = new URLSearchParams({
  grant_type: 'authorization_code',
  code: code,
  client_id: 'CLIENT_ID',
  client_secret: 'CLIENT_SECRET',
  redirect_uri: 'https://site.ru/auth/izek/callback'
});

const tokenResponse = await fetch('https://izek.ru/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: params
});

const token = await tokenResponse.json();

const userResponse = await fetch('https://izek.ru/api/userinfo', {
  headers: { Authorization: `Bearer ${token.access_token}` }
});

const user = await userResponse.json();

10. Ошибки API

Ошибки возвращаются в JSON-формате.

{
  "error": "invalid_client"
}

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

• Используйте только HTTPS для внешнего сайта и Redirect URI.
• Храните client_secret только на сервере. Никогда не вставляйте его в HTML или JS.
• Всегда передавайте и проверяйте state, чтобы защититься от CSRF.
• Не храните access token в открытом виде и не пишите его в публичные логи.
• Проверяйте, что email пользователя подтверждён на вашей стороне, если от этого зависит безопасность.
• При компрометации ключей отключите приложение и создайте новое.

12. Ограничения и совместимость