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 защитава достъпа, вижте в сигурност и контрол на достъпа. Всички връзки са описани в EU интеграции и сигурност.

Добре е да знаете

• Лимит: по подразбиране 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 ключ в профила.