Мастер-токен

Мастер-токен используют для серверных интеграций, где клиентская система выполняет запросы от имени разных пользователей HRlink.

Аутентификация проходит в два этапа. Сначала интегратор формирует Bearer-токен JWT и подписывает его приватным ключом. Затем интегратор вызывает Создать мастер-токен и получает masterToken для запросов к API тенанта.

Что потребуется

Значение	Откуда взять
`tenantHost`	Адрес тенанта HRlink, например `company.hr-link.ru`
`integrator_private.key`	Регистрация интегратора
`integrator.crt`	Регистрация интегратора
`iss`	Регистрация интегратора
`sub`	Регистрация интегратора

Процесс настройки

Быстрый маршрут

Шаг	Что сделать
1	Зарегистрировать интегратора и сертификат
2	Сформировать Bearer-токен JWT
3	Вызвать Создать мастер-токен
4	Передавать `masterToken` и impersonation-заголовки в методы HRlink

Получить мастер-токен

curl
PowerShell
HTTP

curl -X POST "https://esa.hr-link.ru/api/v1/masterTokens" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {integratorToken}" \
  -H "Content-Type: application/json" \
  -d '{"tenantHost": "{tenantHost}"}'

Invoke-RestMethod -Uri "https://esa.hr-link.ru/api/v1/masterTokens" `
  -Method POST `
  -Headers @{
    "Accept" = "application/json"
    "Authorization" = "Bearer {integratorToken}"
  } `
  -ContentType "application/json" `
  -Body '{"tenantHost": "{tenantHost}"}'

POST /api/v1/masterTokens HTTP/1.1
Host: esa.hr-link.ru
Accept: application/json
Authorization: Bearer {integratorToken}
Content-Type: application/json

{"tenantHost": "{tenantHost}"}

Ответ:

{
  "result": true,
  "masterToken": "eyJhbGc..."
}

Срок жизни мастер-токена задаёт Служба заботы при регистрации интегратора. Типичное значение — 10 минут.

Выполнять запросы от имени пользователя

При каждом запросе к API тенанта передавайте мастер-токен и пользователя, от имени которого выполняется запрос.

curl
PowerShell
HTTP

curl -X GET "https://{tenantHost}/api/v2/currentUser" \
  -H "Accept: application/json" \
  -H "Master-Api-Token: {masterToken}" \
  -H "Impersonated-User-Id: {userId}" \
  -H "Impersonated-User-Id-Type: EXTERNAL_ID"

Invoke-RestMethod -Uri "https://{tenantHost}/api/v2/currentUser" `
  -Method GET `
  -Headers @{
    "Accept" = "application/json"
    "Master-Api-Token" = "{masterToken}"
    "Impersonated-User-Id" = "{userId}"
    "Impersonated-User-Id-Type" = "EXTERNAL_ID"
  }

GET /api/v2/currentUser HTTP/1.1
Host: {tenantHost}
Accept: application/json
Master-Api-Token: {masterToken}
Impersonated-User-Id: {userId}
Impersonated-User-Id-Type: EXTERNAL_ID

Заголовки для работы от имени пользователя

Заголовок	Обязательность	Описание
`Impersonated-User-Id`	Да	Идентификатор пользователя
`Impersonated-User-Id-Type`	Да	Тип идентификатора: `HR_LINK_ID`, `SNILS` или `EXTERNAL_ID`
`Impersonated-User-Id-External-System-Type`	Нет	Тип внешней системы, если используете `EXTERNAL_ID` из массива `userExternalIds`

Используйте:

EXTERNAL_ID — если при синхронизации сотрудников передаёте externalId;
HR_LINK_ID — если знаете внутренний UUID пользователя HRlink;
SNILS — если знаете СНИЛС физического лица.

Перевыпуск токенов

Bearer-токен JWT формирует интегратор. Создавайте новый токен до истечения предыдущего.
Мастер-токен выпускайте заново до окончания срока его действия. Количество выпусков не ограничено.

При ошибках 51.205, 51.210 или 22.015 см. ошибки аутентификации.

Что потребуется​

Процесс настройки​

Быстрый маршрут​

Получить мастер-токен​

Выполнять запросы от имени пользователя​

Заголовки для работы от имени пользователя​

Перевыпуск токенов​