Session handling

Authentication in the REST API is implemented through an Auth Token — a unique string generated for a limited period of time after successful client authorisation. An Auth Token is required to access any REST API resource except /auth.

One client can hold only one Auth Token at a time. A new token is generated only after the previous one has expired — if a client sends several authorisation requests within a short period, all responses will return the same token value. The default token expiry time is 60 seconds.

PUT Login

PUT /auth

Authenticates the client and returns an Auth Token. The token must be included in all subsequent API requests via the Api-ClientToken header.

Request attributes

Attribute	Description
Headers
Api-Version	API version. Current value: 1.0.
Api-ClientTransactionId	Unique client-generated transaction identifier for tracing purposes.
Body
login	Client REST API login. Available in the registrar console under Profile → Registrar details.
password	Client REST API password. Available in the registrar console under Profile → Registrar details.

Response attributes

Attribute	Description
Headers
Content-Type	Always `application/json`.
Body
login	Requested login used for authentication.
token	The generated Auth Token.
created	Timestamp when the token was created.
expires	Timestamp when the token will expire.
code	Response code. `1000` if the operation was successful.
message	Response message. Generally a description of the response code.
cltrid	Client transaction ID provided in the request.
svtrid	Server transaction ID generated by ST Registry.
time	Request execution time in seconds.

Request

PUT /auth HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2

{
  "login": "clientX",
  "password": "1q2w3e4r"
}

Response

HTTP/1.1 200 OK
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
}

DELETE Logout

DELETE /auth

Terminates the current Auth Token. After a successful request the token is invalidated immediately and can no longer be used.

Request attributes

Attribute	Description
Headers
Api-Version	API version. Current value: 1.0.
Api-ClientTransactionId	Unique client-generated transaction identifier for tracing purposes.
Api-ClientToken	The active Auth Token to be terminated.
Body
No body parameters.

Response attributes

Attribute	Description
Headers
Content-Type	Always `application/json`.
Body
code	Response code. `1000` if the operation was successful.
message	Response message. Generally a description of the response code.
cltrid	Client transaction ID provided in the request.
svtrid	Server transaction ID generated by ST Registry.
time	Request execution time in seconds.

Error code 2201 is returned when the provided token has expired or is invalid.

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 1000,
  "message": "OK",
  "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
  "svtrid": "3b5a9732-3919-44eb-8a8c-fc504151bb64",
  "time": 0.005012035369873
}

GET Token validation

GET /auth

Validates an existing Auth Token. Use this endpoint to check whether a token has expired, to retrieve its expiry time, or to synchronise with the ST Registry server time.

Request attributes

Attribute	Description
Headers
Api-Version	API version. Current value: 1.0.
Api-ClientTransactionId	Unique client-generated transaction identifier for tracing purposes.
Api-ClientToken	The Auth Token to validate.
Body
No body parameters.

Response attributes

Attribute	Description
Headers
Content-Type	Always `application/json`.
Body
code	Response code. `1000` if the operation was successful.
message	Response message. Generally a description of the response code.
created	Timestamp when the token was created.
expires	Timestamp when the token will expire.
reqtime	Server timestamp identifying when the request was received.
cltrid	Client transaction ID provided in the request.
svtrid	Server transaction ID generated by ST Registry.
time	Request execution time in seconds.

Error code 2201 is returned when the provided token has expired or is invalid.

Request

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

Response

HTTP/1.1 200 OK
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
}