Авторизация

Получение access токена

Чтобы начать работать с API пользователю с ролью “Администратор” необходимо сгенерировать авторизационные токены в личном кабинете. Токены нужны для выполнения запросов в API от лица их создателя. Для авторизации пользователя используется механизм access-токенов из протокола OAuth2.0.

После их генерации менеджер получит ссылку на токены в json-формате:

{
  "name": "Интеграция с Битрикс24",
  "access_token": "OSe5zGs-YU6pVuUOv1dSL2keqEvxAuxo3D888_tzRABX61KS6mB-JfbO8Y77C8hr",
  "expires_in": 86400,
  "refresh_token": "jHNGJFTZmvFDWhLM_7kI7T2wLKVevpcTg_Sw-33i_Mp5GT0gwbL2WRKekLbUG3Vd",
  "refresh_token_expires_in": 10368000,
  "token_type": "bearer",
  "created_at": 1703259897344
}

Параметр	Описание
access_token	Токен, используемый для запросов в API.
expires_in	Время жизни access_token в секундах с даты последнего обновления. По умолчанию 1 день.
refresh_token	Токен, необходимый для обновления истёкшего access_token.
refresh_token_expires_in	Время жизни refresh_token в секундах с даты последнего обновления. По умолчанию 120 дней.
name	Название токена, указанного при создании в личном кабинете.
token_type	Тип токена. В данный момент может быть только “bearer”.
created_at	Время создания токена.

Ссылка перестанет работать через 30 дней после её генерации или после первого обновления полученных по ней токенов.

Использование access токена

При обращении к API необходимо использовать полученный access_token, передавая его в заголовке в формате Authorization: Bearer ACCESS_TOKEN.

Токен можно проверить, сделав GET-запрос на /auth_check:

curl -i "https://api.talantix.ru/auth_check"
-H "Authorization: Bearer OSe5zGs-YU6pVuUOv1dSL2keqEvxAuxo3D888_tzRABX61KS6mB-JfbO8Y77C8hr"

При успешном выполнении запрос вернёт 204 HTTP код.

примечание

Список возможных ошибок приведен на отдельной странице

Обновление access токена

Время жизни access_token ограничено и после его окончания любой запрос к API будет возвращать 401 HTTP код с телом ответа:

{
  "type": "invalid_token",
  "detail": "token_expired"
}

В этом случае необходимо получить новую пару access и refresh токенов через POST-запрос на oauth/token:

Параметр	Тип	Значение
Content-Type	Header	"application/x-www-form-urlencoded".
grant_type	Body	"refresh_token".
refresh_token	Body	Текущий валидный refresh_token.

Пример запроса:

curl -X POST "https://api.talantix.ru/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=jHNGJFTZmvFDWhLM_7kI7T2wLKVevpcTg_Sw-33i_Mp5GT0gwbL2WRKekLbUG3Vd"

Ответ:

{
  "name": "test",
  "access_token": "8ns6bCq5_nhi1wlKHjWyQRyHIjjY6Xm3rrLdhiIIZkUH4bpluJaTybYMjhqTqoUW",
  "expires_in": 86400,
  "refresh_token": "clQ1bOBC9wCLpL-DCPHfwfvtSdKZtHwdaesrPFnH7mt_CtXYFWrJizk-c9gY2CqQ",
  "refresh_token_expires_in": 10368000,
  "token_type": "bearer"
}

Значения идентичны описанию параметров при получении токена.

Ошибки обновления access токена

Ошибки возвращаются в json формате.

HTTP code	error	error_description
400	invalid_grant	Refresh token is invalid, expired or revoked.
400	unsupported_grant_type	The authorization grant type is not supported by the authorization server.

Пример:

{
  "error": "invalid_grant",
  "error_description": "Refresh token is invalid, expired or revoked"
}

примечание

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

warning

Время жизни refresh_token ограничено параметром refresh_token_expires_in. После его истечения не получится обновить access и refresh токены. В таком случае нужно создать новую пару токенов в личном кабинете.