REST API Xcellerate OPS з особистими API-ключами

Xcellerate OPS має задокументований REST API (v1). З його допомогою ви підключаєте власні інструменти, скрипти або платформи автоматизації до тікетів, компаній, контактів, угод, проєктів, записів часу, активів тощо. Кожен користувач створює власні API-ключі у своєму профілі, і ключ може рівно те, що цей користувач може в застосунку, не більше. Цей посібник для технічних адміністраторів MSP і сервісних компаній.

TL;DR

• Створіть ключ у профілі в розділі API keys і одразу скопіюйте токен: його показують лише один раз.
• Надсилайте з кожним запитом два заголовки: Authorization: Bearer <token> і X-Tenant-Id.
• Ключ успадковує права вашого користувача. За замовчуванням ліміт становить 120 запитів на хвилину на ключ.

Перш ніж почати

• Будь-який співробітник може створювати ключі для себе. Роль адміністратора не потрібна.
• Права ключа один до одного відповідають правам вашої команди. Що заблоковано в застосунку, заблоковано і в API.
• Вам потрібен HTTP-клієнт, що вміє надсилати заголовки: скрипт, платформа автоматизації або ваш власний застосунок.
• На одного користувача можна мати до 20 активних ключів.

Зверніть увагу: розділ API-ключів у застосунку доступний лише англійською, тому назви нижче подано англійською.

Створення та використання API-ключа

Крок 1: Відкрийте API-ключі

Перейдіть у свій профіль і відкрийте розділ API keys (API-ключі).

Крок 2: Створіть ключ

Дайте ключу назву, яка пояснює його призначення. Оберіть, чи може він лише читати, чи також записувати, і за потреби встановіть дату закінчення дії в майбутньому. Ключі працюють лише на читання, якщо ви не створите їх із правом запису. Якщо вам потрібне лише читання даних, так і залиште.

Крок 3: Скопіюйте токен

Після створення OPS показує повідомлення «Copy your new API key now — it will not be shown again.» Одразу скопіюйте токен і збережіть його в безпечному місці. Токени починаються з xok_. Якщо ви його втратили, створіть новий ключ.

Крок 4: Скопіюйте ID робочого простору

У цьому ж розділі показано ID вашого робочого простору (tenant id). Скопіюйте його кнопкою Copy (Копіювати). Він потрібен для кожного запиту.

Крок 5: Зробіть перший запит

Перевірте ключ простим запитом до /api/v1/me з обома заголовками:

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

Посилання API documentation ↗ (документація API) у розділі відкриває інтерактивну документацію. Перевірте там правильну базову адресу та доступні endpoints.

Крок 6: Відкликайте ключі, якими більше не користуєтеся

Ключ відкликається з того самого списку. Для кожного ключа видно час останнього використання, тож легко знайти ключі, які вже нікому не потрібні.

Що відбувається після підключення

• Формат: JSON для запитів і відповідей. Списки розбито на сторінки за допомогою курсора.
• Охоплення: серед іншого компанії, контакти, взаємодії CRM, користувацькі поля, тікети та розклади тікетів, проєкти з плануванням і фінансами, записи часу, витрати, відсутності, робочий час, активи та CMDB, програмне забезпечення, послуги, changes, problems, major incidents, releases, база знань, угоди, тарифні сітки, регулярні рахунки, звіти, звіти SLA та XLA, дзвінки й записи та журнал дій AI. Повний список є в документації API.
• Клієнтський портал: клієнти, які користуються вашим клієнтським порталом, можуть створювати там власні ключі. Такі ключі бачать лише власні дані клієнта.

Як OPS захищає доступ, читайте в розділі безпека та контроль доступу. Усі підключення описано в розділі інтеграції ЄС і безпека.

Корисно знати

• Ліміт: за замовчуванням 120 запитів на хвилину на ключ. RMM Labs може підвищити його для робочого простору на запит. Кожна відповідь містить заголовки X-RateLimit-Limit і X-RateLimit-Remaining.
• Невдалі автентифікації: повторні невдалі спроби з тієї самої адреси тимчасово блокуються.
• Ключі належать людині. Вимкнення користувача відкликає його ключі та блокує доступ. Інтеграції, що працюють на цих ключах, зупиняються. Враховуйте це, коли співробітник іде.
• Особисті налаштування, наприклад параметри синхронізації календаря, недоступні через API.

Усунення проблем

• 401 unauthenticated «Invalid API credentials.» Токен неправильний, прострочений або відкликаний, X-Tenant-Id відсутній чи хибний, робочий простір призупинено або користувача вимкнено. Усі ці випадки навмисно дають однакову відповідь.
• 429 rate_limited «Too many requests.» Зачекайте кількість секунд із заголовка Retry-After.
• 429 «Too many failed authentication attempts.» Вашу IP-адресу тимчасово заблоковано після повторних невдач.
• «You have reached the maximum number of API keys.» У вас 20 активних ключів. Спочатку відкличте один.

Почніть

Хочете підключити OPS до власних скриптів та інструментів? Почніть безкоштовно і створіть перший API-ключ у профілі.