Contents
Authentication in REST API is implemented through Auth Token.
Auth Token – unique string which is generated for limited period of time after successful client authorisation which is required to access any REST API resource by the client except “/auth” resource. One client is able to generate only 1 Auth token, new token is generated only if previous one has expired. This mean that if client will send several authorisation request within short period of time (until auth token expire) – all responses will contain same auth token value. Currently default expire time for token is 60 seconds.
Login
URI: /auth
Request method: PUT
| Name | Description |
|---|---|
| login | Client REST API login. Acquired by the registrar in their registrar console by visiting page “Profile” -> “Registrar details” |
| password | Client REST API password. Acquired by the registrar in their registrar console by visiting page “Profile” -> “Registrar details” |
Request example:
|
1 2 3 4 5 6 7 8 9 10 11 |
PUT /auth HTTP/1.1 Host: apihost Content-Type: application/json Content-Length: 53 Api-Version: 1.0 Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2 { "login": "clientX", "password": "1q2w3e4r" } |
After successful authentication request, response will contain following elements:
- login – requested login to authenticate.
- token – auth token.
- created – timestamp when token was created.
- expires – timestamp when token will expire.
- code – response code. 1000 if operation successful.
- message – response message. Generally its a description for response code.
- cltrid – client transaction ID which was provided in request.
- svtrid – server transaction ID which was generated by ST Registry for corresponding request.
- time – request execution time in seconds.
Response example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
HTTP/1.1 200 OK Date: Tue, 01 Jan 2014 00:00:01 GMT Server: Apache/2.2.15 (CentOS) X-Powered-By: PHP/5.4.11 Connection: close Transfer-Encoding: chunked Content-Type: application/json { "login": "clientX", "token": "4e2f9057932d12892b83adaae3484bd8", "created": "2013-12-18T08:56:20+00:00" "expires": "2013-12-18T08:57:20+00:00" "code": 1000, "message": "OK", "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2", "svtrid": "5230303c-56e7-4615-a179-f1d29ef9949a", "time": 0.012043952941895 } |
Logout
Client is able to terminate Auth Token using DELETE request method. If request is successful – ST Registry will terminate provided Auth token.
URI: /auth
Request method: DELETE
Request example:
|
1 2 3 4 5 6 |
DELETE /auth HTTP/1.1 Host: apihost Content-Type: application/json Api-Version: 1.0 Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2 Api-ClientToken: 1a2B3C4d5e6F |
After successful request, response will contain following elements:
- code – response code. 1000 if operation successful.
- message – response message. Generally its a description for response code.
- cltrid – client transaction ID which was provided in request.
- svtrid – server transaction ID which was generated by ST Registry for corresponding request.
- time – request execution time in seconds.
Response example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
HTTP/1.1 200 OK Date: Tue, 01 Jan 2014 00:00:01 GMT Server: Apache/2.2.15 (CentOS) X-Powered-By: PHP/5.4.11 Connection: close Transfer-Encoding: chunked Content-Type: application/json { "code": 1000, "message": "OK", "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2", "svtrid": "3b5a9732-3919-44eb-8a8c-fc504151bb64", "time": 0.005012035369873 } |
If token has expired or is invalid – response code “2201” will be returned to the client request.
Auth token validation
Client is able to validate existing Auth token to verify if token has not expired yet on ST Registry side, get information when its going to expire or just to synchronise with ST Registry server time.
URI: /auth
Request method: GET
Request example:
|
1 2 3 4 5 6 |
GET /auth HTTP/1.1 Host: apihost Content-Type: application/json Api-Version: 1.0 Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2 Api-ClientToken: 1a2B3C4d5e6F |
After successful request, response will contain following elements:
- code – response code. 1000 if operation successful.
- message – response message. Generally its a description for response code.
- created – timestamp when token was created.
- expires – timestamp when token will expire.
- reqtime – server timestamp which identify when request was made.
- cltrid – client transaction ID which was provided in request.
- svtrid – server transaction ID which was generated by ST Registry for corresponding request.
- time – request execution time.
Response example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
HTTP/1.1 200 OK Date: Tue, 01 Jan 2014 00:00:01 GMT Server: Apache/2.2.15 (CentOS) X-Powered-By: PHP/5.4.11 Connection: close Transfer-Encoding: chunked Content-Type: application/json { "code": 1000, "message": "OK", "created": "2013-12-18T08:56:20+00:00" "expires": "2013-12-18T08:57:20+00:00" "reqtime": "2013-12-18T08:56:35+00:00", "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2", "svtrid": "3b5a9732-3919-44eb-8a8c-fc504151bb64", "time": 0.005012035369873 } |
If token has expired or is invalid – response code “2201” will be returned to the client request.
