Авторизация и токены IZI API

Авторизация и токены IZI API

IZI API использует JWT (JSON Web Token) — стандартный механизм авторизации без хранения сессий на сервере. Два токена: короткоживущий accessToken для запросов и долгоживущий refreshToken для его обновления.

Шаг 1 — Получить токен

mutation Login($email: String!, $password: String!) {
  loginWithEmailPassword(email: $email, password: $password) {
    accessToken
    refreshToken
    user {
      id
      email
      role
    }
  }
}

{
  "email": "partner@example.com",
  "password": "your_password"
}

Ответ:

{
  "data": {
    "loginWithEmailPassword": {
      "accessToken": "eyJhbGciOiJSUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
      "user": {
        "id": "user_abc123",
        "email": "partner@example.com",
        "role": "ADMIN"
      }
    }
  }
}

Сохраните оба токена. accessToken — в памяти процесса, refreshToken — в защищённом хранилище (не в localStorage браузера, не в открытом файле).

Шаг 2 — Использовать токен

Передавайте accessToken в заголовке каждого запроса:

curl -X POST https://api.izi.is/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{"query": "query { me { id email } }"}'

В коде — один раз настройте HTTP-клиент:

const client = new GraphQLClient('https://api.izi.is/graphql', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

Шаг 3 — Обновить токен

accessToken живёт 15 минут. Обновляйте его заранее — не ждите ошибки TOKEN_EXPIRED во время важного запроса.

mutation RefreshToken($token: String!) {
  refreshToken(token: $token) {
    accessToken
    refreshToken
  }
}

{
  "token": "eyJhbGciOiJSUzI1NiIs... (ваш refreshToken)"
}

После каждого вызова refreshToken сохраняйте оба новых токена — старый refreshToken становится недействительным.

Схема ротации токенов

              ┌─────────────────────────────────┐
              │         Ваш сервис               │
              │                                 │
              │  accessToken  ──────────────────►│──► API запросы
              │  (TTL: 15 мин)                  │
              │                                 │
              │  refreshToken ──────────────────►│──► refreshToken mutation
              │  (TTL: 30 дней)  ◄──────────────│    → новые оба токена
              └─────────────────────────────────┘

Рекомендуемая стратегия: обновлять accessToken за 2–3 минуты до истечения (по истечении 12–13 минут с момента получения).

Обработка TOKEN_EXPIRED в middleware

async function requestWithRetry(query, variables) {
  try {
    return await client.request(query, variables);
  } catch (error) {
    if (error.extensions?.code === 'TOKEN_EXPIRED') {
      // Обновляем токен
      const { refreshToken: newRefresh, accessToken: newAccess } =
        await refreshTokens(currentRefreshToken);

      // Сохраняем новые токены
      currentAccessToken = newAccess;
      currentRefreshToken = newRefresh;

      // Обновляем заголовок клиента
      client.setHeader('Authorization', `Bearer ${newAccess}`);

      // Повторяем исходный запрос
      return await client.request(query, variables);
    }
    throw error;
  }
}

Выход / инвалидация токена

mutation Logout($refreshToken: String!) {
  logout(refreshToken: $refreshToken) {
    success
  }
}

После этого оба токена (access и refresh) становятся недействительными немедленно.

Роли и разрешения

Токен содержит роль пользователя. В IZI есть одна встроенная роль для сотрудников — Администратор — плюс произвольное количество кастомных ролей, которые владелец создаёт сам.

Сущность	Тип	Описание
Владелец (Owner)	Владение организацией	Пользователь, создавший организацию. Полный доступ ко всему. Это не назначаемая роль, а статус владельца.
Администратор (Administrator)	Встроенная роль	Единственная предустановленная роль сотрудника. Базовые права на уровне назначенных клубов.
Кастомная роль	Создаётся владельцем	Владелец задаёт название, выбирает набор разрешений (clubPermissions / orgPermissions) и опционально полный доступ. Редактируется и удаляется.

Чтобы дать сотруднику профиль «менеджер» или «кассир» — создайте кастомную роль с нужным названием и выберите точный набор разрешений. Готовых ролей с такими именами в системе нет.

Для серверных интеграций создавайте отдельного пользователя с кастомной ролью, ограниченной минимально необходимыми разрешениями. Не используйте личный аккаунт владельца.

Связанные страницы

• IZI API: обзор — общая архитектура
• Коды ошибок API — полный список кодов включая auth-ошибки
• Примеры SDK — готовые обёртки с автоматическим refresh

См. также

• IZI API: обзор для разработчиков
• Коды ошибок IZI API
• Основы GraphQL в IZI
• Ограничения частоты запросов IZI API
• Примеры SDK IZI: JavaScript и Python