Via OAuth 2.0 protocol the users may register their applications for operation with API of RU-CENTER services.
OAuth 2.0 is based on the use of basic web technologies: HTTP-requests, redirects, etc. So OAuth 2.0 may be used on any platform having Internet access and browser: on websites, mobile and desktop applications or plug-ins for browsers.
For development and further use of API the application it would be required to register application on RU-CENTER OAuth server and pass token obtaining procedure. Then, the obtained token may be used in requests to RU-CENTER API services.
For registration procedure you should log in to "Manage your account".
For register the application on RU-CENTER OAuth server, you are required to take the following steps:
Application password (client_secret setting of OAuth 2.0 ptocol) may be changed in "Applications management" section.
For obtaining request through API of RU-CENTER services the customer and application through which the request has been made should be authenticated. Each request is marked with the token issued by RU-CENTER OAuth server. Generally, the token is transferred in Authorization HTTP heading. For GET request the token may be transferred as token setting.
The token is used instead of application owner's name and password. The token access area is set during token issue via scope setting, which receives the list of allowed areas (regular expressions) separated by spaces.
All requests to OAuth server shall be transferred to HTTPS protocol.
The request has the following look:
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%3Fdns-master%2F.%2B
In Authorization heading the line <client_id>:<client_secret> encoded via base64 is transferred. Here <client_id> is application identifier, <client_secret> - application password (both attributes are generated upon registration of the application).
Used settings:
grant_type - type of response. Required setting, grant_type setting is always assigned with password value.
username - user login. The agreement number is used as user login, for example, username=123/NIC-REG.
password - user password. Administrative or technical passwords may be used, for example, password=qwerty.
scope - is a sequence of regular expressions, separated by spaces which describe the access area of the application.
To obtain reissue token it will be required to set offline parameter with no-zero value in the access token request.
The request has the following look:
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
Used settings:
grant_type - type of response. Required setting, grant_type setting is always assigned with password value.
username - user login. The agreement number is used as user login, for example, username=123/NIC-REG.
password - user password. Administrative or technical passwords may be used, for example, password=qwerty.
scope - is a sequence of regular expressions, separated by spaces which describe the access area of the application.
client_id - application identifier generated upon application registration, for example: client_id=123123.
client_secret - application password generated upon application registration, for example: client_secret=appp123123.
To obtain reissue token it will be required to set offline parameter with no-zero value in the access token request.
In case of success OAuth server will communicate data as JSON document:
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"
}
Response settings:
access_token - token to be handled by the application on behalf of the user name.
expires_in - access token lifetime. The value is indicated in seconds.
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
Chach-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
HTTP code of response may be 400, 401. Apart from error the response body may have additional settings, for example:
invalid_request - invalid request formatinvalid_grant - invalid or expired confirmation codeunsupported_grant_type - invalid setting value grant_typeRefreshing access tokens is made via refresh token to be obtained in course of access token refresh (for confidential customers).
The request has the following look:
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
In Authorization HTTP heading the line <client_id>:<client_secret> encoded via base64 is to be transferred. Here <client_id> is application identifier, <client_secret> application password (both attributes are generated upon registration of the application).
Setting grant_type=refresh_token, and setting refresh_tokenshall contain refreshed token value (for example: refresh_token=tGzv3JOkF0XG5Qx2TlKWIA).
Alternative option, transfer of client_id and client_secret settings is used instead of Authorization heading:
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 code of response may be 400, 401. Apart from error the response body may have additional settings, for example:
invalid_request - invalid request formatinvalid_grant - invalid or expired confirmation codeunsupported_grant_type - invalid setting value grant_type