Регистрация
Получение токена
Перевыпуск токена доступа
Регистрация
По протоколу OAuth 2.0 пользователи могут зарегистрировать свои приложения для работы с API сервисов Руцентра.
OAuth 2.0 основан на использовании базовых веб-технологий: HTTP-запросах, редиректах и т. п. Поэтому использование OAuth 2.0 возможно на любой платформе с доступом к интернету и браузеру: на сайтах, в мобильных и desktop-приложениях или плагинах для браузеров.
Для разработки приложения и дальнейшей его работы с API необходимо зарегистрировать приложение на OAuth-сервере Руцентра и пройти процедуру получения токена. После чего полученный токен можно использовать в запросах к API сервисов Руцентра.
Регистрация приложения.
Для выполнения процедуры регистрации необходимо авторизоваться в личном кабинете. Чтобы зарегистрировать приложение на OAuth-сервере Руцентра, выполните следующие действия:
- Перейдите на страницу регистрации приложения.
- Укажите название вашего приложения в поле Название приложения.
- Нажмите на кнопку Зарегистрировать приложение.
- После регистрации приложения OAuth-сервер Руцентра сгенерирует идентификатор и пароль приложения (параметры client_id и client_secret протокола OAuth 2.0), которые нужно будет указать при запросе токена.
Управление приложениями. Сменить пароль приложения (параметр client_secret протокола OAuth 2.0) можно в разделе Управление приложениями.
Получение токена
При получении запроса через API сервисов Руцентра необходимо аутентифицировать клиента и приложение, через которое был послан запрос. Каждый запрос маркируется токеном, выданным OAuth-сервером Руцентра. Как правило, токен передается в HTTP-заголовке Authorization. Для GET-запроса токен может быть передан как параметр token.
Токен используется вместо имени и пароля владельца приложения. Область доступа токена задается при выпуске токена, через параметр scope, который на вход принимает список допустимых областей (регулярные выражения), разделенных пробелами.
Все запросы к OAuth-серверу должны передаваться по протоколу HTTPS.
Запрос с использованием базовой HTTP-авторизации
Запрос имеет вид:
POST https://api.nic.ru/oauth/token HTTP/1.1
Authorization: Basic <base64-encoded-string>
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=login&password=A3ddj3w&scope=GET%3A%2Fdns-master%2F.%2B
В заголовке Authorization передается строка <client_id>:<client_secret>, закодированная методом base64. Здесь <client_id> — идентификатор приложения, <client_secret> — пароль приложения (оба атрибута генерируются после регистрации приложения).
Используемые параметры:
grant_type — тип ответа. Обязательный параметр, параметру grant_type всегда присваивается значение password;
username — логин пользователя. В качестве логина пользователя используется договор, например, username=123/NIC-REG;
password —пароль пользователя. Можно использовать административный или технический пароль, например, password=qwerty;
scope —это последовательность регулярных выражений, разделенных пробелами, которые описывают область доступа приложения.
Для получения токена перевыпуска в запросе на получение токена доступа необходимо задать параметр offline со значением, отличным от нуля.
Параметр запроса командой curl:
curl --location --request POST 'https://api.nic.ru/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=xxxxxxxxxxxxxxxx' \
--data-urlencode 'client_id=xxxxxxxxxx' \
--data-urlencode 'client_secret=xxxxxxxxxxxxx' \
--data-urlencode 'username=xxxxxxx/NIC-D' \
--data-urlencode 'scope=.*'Запрос в случае явной передачи идентификатора и пароля приложения
Запрос имеет вид:
POST https://api.nic.ru/oauth/token HTTP/1.1
Content-Type: application/x-www-from-urlencoded
grant_type=password&username=123/NIC-D&password=A3ddj3w&scope=GET%3A%3Fdns-master%2F.%2B&client_id=123123&client_secret=appp123123
Используемые параметры:
grant_type — тип ответа. Обязательный параметр, параметру grant_type всегда присваивается значение password;
username — логин пользователя. В качестве логина пользователя используется договор, например, username=123/NIC-REG;
password — пароль пользователя. Можно использовать административный или технический пароль, например, password=qwerty;
scope — это последовательность регулярных выражений, разделенных пробелами, которые описывают область доступа приложения;
client_id — идентификатор приложения, который генерируется после регистрации приложения, например: client_id=123123;
client_secret — пароль приложения, генерируется после регистрации приложения, например: client_secret=appp123123.
Для получения токена перевыпуска в запросе на получение токена доступа необходимо задать параметр offline со значением, отличным от нуля.
Формат ответа в случае успеха
В случае успеха OAuth-сервер передает данные как JSON-документ:
HTTP/1.1 200 OK
Content-Type: application/json;charset-UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Параметры ответа:
access_token — токен, с которым приложение может работать от имени пользователя;
expires_in — время жизни токена доступа. Значение указывается в секундах.
Формат ответа в случае ошибки
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
Chach-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
HTTP-код ответа может быть 400, 401. В теле ответа помимо error могут быть дополнительные параметры, например:
invalid_request — неверный формат запроса;
invalid_grant — неверный или просроченный код подтверждения;
unsupported_grant_type — неверное значение параметра grant_type.
Перевыпуск токена доступа
Перевыпуск с использованием схемы Authorization Basic
Перевыпуск токенов доступа осуществляется через токен перевыпуска (refresh token), который должен быть получен во время выпуска токена доступа (для конфиденциальных клиентов).
Запрос имеет вид:
POST https://api.nic.ru/oauth/token HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
В HTTP-заголовке Authorization передается строка <client_id>:<client_secret>, закодированная методом base64. Здесь <client_id> - идентификатор приложения, <client_secret> - пароль приложения (оба атрибута генерируются после регистрации приложения).
Параметр grant_type=refresh_token, а параметр refresh_token должен содержать значениe токена перевыпуска (например: refresh_token=tGzv3JOkF0XG5Qx2TlKWIA).
Перевыпуск в случае явной передачи идентификатора и пароля
Альтернативный вариант, вместо заголовка Authorization используется передача параметров client_id и client_secret:
POST https://api.nic.ru/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=app12312312&client_secret=password
Формат ответа в случае успеха
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
}
Формат ответа в случае ошибки
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
HTTP-код ответа может быть 400, 401. В теле ответа помимо error могут быть дополнительные параметры, например:
invalid_request — неверный формат запроса;
invalid_grant — неверный или просроченный код подтверждения;
unsupported_grant_type — неверное значение параметра grant_type.