xRM позволяет использовать системный API во внешних приложениях. Права приложений определяют назначенные им роли (см. ниже).

1.

Ключ

Начиная с версии 2.0.4, появилась авторизацию в API состоит из 2х этапов:

1. Авторизация приложения 
2. Авторизация пользователя

Есть сущность «приложение», которой присваивается уникальный ключ APP_KEY. Приложения, не предоставившие правильный ключ при включенной проверке ключей, не допускаются к использованию API. Если ключ передан и валиден, то его достаточно, чтобы увидеть описание доступных приложению методов в API панели. Набор доступных приложению методов регулируется ролью на видимость. 

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

1.1. Проверка ключа

APP_KEY необходимо передавать при каждом запросе к API.

Ключ проверяется только в том случае, если системная переменная CHECK_APP_KEY (ID: 100030000000000248382) имеет значение 1. Переменная отключена по умолчанию на инсталляциях до версии 2.0.4.*. При обновлении старой инсталляции она также останется отключенной (если не включить вручную) для обратной совместимости. В случае установки xRM2.0.4.* (и старше) на «чистый» сервер переменная по умолчанию включена.

1.1.1. Возможные ошибки проверки ключа

При попытке авторизоваться без ключа app_key (при включенном параметре CHECK_APP_KEY) система выдаст ошибку: [366] Ключ приложения отсутствует или некорректен.

При попытке использовать API-метод без передачи ключа app_key вы получите ошибку: Authentication parameter APP_KEY is invalid or missing.

1.1.2. Проверка текущего значения переменной CHECK_APP_KEY

В поле поиска введите идентификатор 100030000000000248382.

Перейдите по ссылке на найденный объект. Откройте вкладку Значения в БД.

Найдите текущее значение переменной.

Anchor
a_plan a_plan

1.2. План миграции после обновления версии ниже 2.0.4

Если у вас стояла версия < 2.0.4 и после обновления вы хотите перейти на полноценную проверку ключей, то примерная последовательность действий выглядит так:

1. Проверить, что CHECK_APP_KEY = 0
2. Завести в системе все приложения, которые используют API, получить для каждого APP_KEY
3. Создать роли на видимость для каждого приложения или оставить их пустыми для старого поведения.
4. Доработать каждое приложение, чтобы оно передавало APP_KEY
5. Проверить работу этих приложений
6. Поменять системный параметр CHECK_APP_KEY = 1
   
   

2. Создание нового

приложения

Перейдите в раздел Разделение полномочий | Приложения.

Нажмите кнопку Добавить. Заполните поля в карточке нового ключа.

Укажите Наименование.

В поле Тип выберите Ключ.

В поле Роль на видимость можно указать роль, которая ограничит перечень доступных приложению методов. Подробнее ниже.

Как обычно, выберите группу.

Нажмите Добавить. После нажатия кнопки Добавить система создаст новый ключ:

Image Added

Укажите Наименование.

В поле Тип выберите Ключ.

Если поле Роль на видимость заполнено, ключу доступны те же функции API, что и выбранной роли. Заполнение поля необязательно. Укажите роль, если хотите ограничить доступ приложения к API.

Как обычно, выберите группу.

Нажмите Добавить. После нажатия кнопки Добавить система создаст новый ключ:

Image Removed

2.1. Свойства ключа

2.1. Роль на видимость

Указывается для приложения и содержит просто перечень доступных приложению методов. Даже если этим приложением воспользуется пользователь с очень мощными правами, то приложение сможет звать только тот перечень методов, который ему определили в "Роли на видимость". Рассмотрим на примере:

Есть 3 метода: 

• Метод А. Есть доступ у приложения и у пользователя. Его описание будет видно в wsdl, т.к. для этого достаточно полномочий приложения, и позвать его можно будет, потому что у пользователя также есть на него разрешение.
• Метод B. Есть доступ у приложения, но не у пользователя. Его описание будет видно в wsdl, т.к. для этого достаточно полномочий приложения, а вот позвать его не получится, т.к. пользователю он не доступен.
• Метод C. Нет доступа у приложения, но есть у пользователя. Его описание не будет видно в wsdl, т.к. полномочий у приложения нет, и позвать его поэтому не получится, даже если пользователю он доступен.

Если коротко, то для вызова доступны методы являющиеся результатом пересечения прав пользователя и прав приложения.

Image Added

Роль на видимость не обязательное поле на данный момент у приложения. Это сделано для облегчения миграции приложений, которые до этого не использовали APP_KEY и неизвестно какие методы им вообще нужны. Если поле не заполнено, то фактически приложение работает наполовину в старом режиме: после авторизации приложения не видно никаких методов в API панели, кроме open_session/close_session, а после авторизации пользователя доступны все методы которые доступны пользователю. Таким образом уже происходит 2х этапная авторизация и можно включать проверку CHECK_APP_KEY, но приложение никак не ограничено тем, какие методы может использовать.

2.2. Экземпляры приложения

Открыв карточку приложения, вы увидите, что в ней появилась вторая вкладка: Установленные экземпляры. Если приложение, использующее этот ключ, установлено на одно или несколько мобильных устройств, во вкладке будет выведен список экземпляров приложения:

3. Использование ключа

Ключ app_key необходимо передавать при каждом запросе.

При попытке авторизоваться без ключа app_key (при включенном параметре CHECK_APP_KEY) система выдаст ошибку: [366] Ключ приложения отсутствует или некорректен.

При попытке использовать API-метод без передачи ключа app_key вы получите ошибку: Authentication parameter APP_KEY is invalid or missing.