Registration
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.
Application registration
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:
- Go to page with application registration.
- Specify the name of your application in "Application name" field.
- Click on "Register application" button.
- Upon application registration RU-CENTER OAuth server will generate application identifier and password (client_id and client_secret settings of OAuth 2.0 protocol) to be specified in token request.
Applications management
Application password (client_secret setting of OAuth 2.0 ptocol) may be changed in "Applications management" section.
Obtaining token
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.
Request involving basic HTTP authorization
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.
Request in case of explicit transfer or identifier and application password
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.
Response format in case of success
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.
Response format in case of error
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 valuegrant_type
Refreshing access token
Refreshing through the Authorization Basic scheme
Refreshing 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).
Refreshing in case of explicit transfer or identifier and password
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
Response format in case of success
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",
}
Response format in case of error
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 valuegrant_type