Партнерский API

Okerr имеет API для компаний-партнеров (таких как хостинг-провайдеры), служащий для более удобной интеграции.

Для получения доступа к партнерскому API необходимо получить партрерский логин и пароль.

При обращении к API необходимо указывать логин и пароль через механизм HTTP AUTHORIZATION.

API позволяет создавать пользователей в okerr, получать по ним данные, обеспечивать беспарольный вход пользователей в okerr (single-sign on, через службу аутентификации провайдера по протоколу OAUTH2 (RFC 6749), а так же повышать привилегии пользователя в okerr.

Все функции работы с пользователями работают только с пользователями, которые "принадлежат" этому партнеру.

Определенные функции могут быть включены или отключены (например, REVOKE не должен требоваться партнеру). Если вы получаете сообщение об ошибке - сообщите нам.

Функции API

CHECK

CHECK выдает сводные данные о пользователе в формате JSON.

Для обращения необходимо указать уникальный ID пользователя на системе партнера (например, номер его договора. В примере ниже, id пользователя - "1").

Выдается email пользователя, а так же для всех проектов выдается textid проекта, его имя, общая сводка по индикаторам (количество индикаторов в каждом состоянии), а так же список индикаторов в состоянии ERR.

$ curl -u partner_name:partner_pass https://cp.okerr.com/api/partner/check/1 
{
    "email": "okerrdemo@maildrop.cc",
    "membership": [
        {
            "exp": "20180121",
            "exp_unixtime": 1516535355,
            "group": "perk:qindicator:1h:10"
        },
        {
            "exp": "20180121",
            "exp_unixtime": 1516536353,
            "group": "Cursa"
        }
    ],
    "projects": [
        {
            "err": [
                "antispam:ngs.ru:sorbs",
                "ping:BAD"
            ],
            "name": "okerr demo project",
            "sum": {
                "ERR": 2,
                "OK": 32
            },
            "textid": "okerrdemo"
        }
    ],
    "server": "https://charlie.okerr.com/"
}

CREATE

CREATE создает пользователя в okerr. Используется HTTP метод POST, необходимо передать параметры:

  • email - верифицированный адрес электронной почты пользователя
  • partner_id - уникальный id пользователя у партнера (номер договора).
  • template - шаблон для первоначальной преднастройки индикаторов (например, для первоначального наблюдения за сервером)

Будет создан пользователь и на выходе метод CREATE выдаст первоначальный пароль пользователя, который нужно будет передать ему.

$ curl -u partner_login:partner_pass -d 'email=aaa@bbb.com&partner_id=2&template=minimal' https://cp.okerr.com/api/partner/create
V48bUMsPAP

GRANT

GRANT дает указанный уровень (тарифный план) пользователю на 31 день (от сегодняшнего дня). Рекомендуется выполнять ежедневно. Например, в ситуации, когда клиент провайдера оплатил дополнительные услуги мониторинга или перешел на более высокий тарифный план, предусматривающий более высокий уровень мониторинга.

$ curl -u partner_login:partner_pass -d 'group=Diadem&partner_id=1' https://cp.okerr.com/api/partner/grant
Granted Diadem to user test:1

$ curl -u partner_login:partner_pass https://cp.okerr.com/api/partner/grant -d 'group=perk:qindicator:1h:10&new=1&partner_id=1'
Granted perk:qindicator:1h:10 to user test:1

Если дополнительно указывается параметр new=1, то указанная группа добавляется, даже если она есть. (Это нужно для доп. услуг, каждая из которых может подключаться несколько раз). Если же new=0 или не указано вообще, тогда в случае, если пользователь уже подключен к этой группе, срок действия продлевается еще на 30 дней.

В случае, если пользователь перестает оплачивать дополнительную услугу или уходит от провайдера, уровень доступа прекратится по истечении 30 дней от последнего гранта.

REVOKE

REVOKE отключает пользователя от указанной группы. Для выполнения требуется указывать параметр exp, в формате YYYYMMDD, как он выдается фукцией CHECK.

$ curl -u partner_login:partner_pass https://cp.okerr.com/api/partner/revoke -d 'group=perk:qindicator:1h:10&partner_id=1&exp=20180121'
Revoked perk:qindicator:1h:10 from user test:1

Технология единого входа (Single Sign-On, OAUTH2)

Партнер может обеспечить у себя поддержку авторизации по протоколу OAUTH2 в минимальном виде, с предоставлением данных о email адресе пользователя. Это позволит сделать "беспарольный" переход из контрольной панели провайдера в okerr.

Пример этого, можно увидеть в демонстрационной контрольной панели провайдера. Исходный код проекта можно скачать с гитхаб: https://github.com/yaroslaff/demoisp.

В случае, если нужна помощь, разработчики okerr могут помочь с настройкой OAUTH2 сервера и интеграции с okerr.