This is an archive version of the document. To get the most up-to-date information, see the current version.Authorization and Security
To start working with VAO RESTful API, clients must first authenticate themselves. VAO RESTful API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.
- Access token is a string that represents authorization issued to the client and that must be used in all requests during the current logon session.
- Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token when the current access token expires.
VAO RESTful API authorization process involves the following procedures:
To obtain a pair of tokens, the client sends the POST HTTPS request to the VAO token path. The request body must contain the credentials of a user with the Site Administrator or Failover Plan Author privileges.
|
Simultaneous sessions initiated in different client applications under the same user credentials may interfere with each other. To avoid unexpected logout, use a different user account for every application. |
A successfully completed operation returns the 200 Success response code, and also an access and refresh tokens in the response body. The client inserts the access token in headers of further requests to VAO RESTful API. The refresh token must be saved locally.
|
To learn how to authorize your access using a client application, you can review section Example Requests and Responses. Alternatively, you can use Swagger UI. |
To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTPS request with the refresh token in the request body to the VAO RESTful API token path. A successfully completed operation returns the 200 Success response code and a new pair of tokens in the response body.
When the client finishes working with VAO RESTful API, he logs out by sending the POST HTTPS request to the v1/Accounts/Logout path. A successfully completed operation returns the 200 Success response code and the “Logout successful” message in the response body.
Example Requests and Responses
The following example illustrates how the client and server communicate using requests and responses.
- To obtain an access and refresh tokens, the client sends a POST request to the /token path.
In the body of the request, the client specifies the following parameters:
- grant_type — the authorization process requires that the password value must be specified for this parameter.
- username and password — credentials used to access the server; in this example, vao\administrator and Password1 are used.
Request: POST https://uwin2012r2.n.local:9899/v1/Accounts/Token
Request Header: content-type: application/json
Request Body: grant_type=password&username=vao\administrator&password=Password1 |
The server sends a response in the following format.
Response: 200 Success Response Body: { "access_token": "908qldKH7ZZRfCqeWBNVVbnIM5UxisItP6gSnU_pZ5-qDenA5I2T0XvynyoELoEFmUUzm17_WuodIl1yRnneI15UzsgFnxlsHdhH9KQKFWKrR08PKRh-wL_NXj8PirXUa4PjK3Dx1pE-qCJh23FrrljIjsNjWeDFd63yY4j8ldyqP7fdx6bmp-hWwergK7va89AKEuYzIr_IQNir2yZMgVnXR-FqyEVw_xf_e3sFGJw", "token_type": "bearer", "expires_in": 3599, "refresh_token": "EVU7FlFLT2emhwfwnbwM-RiuD0oHjCIGTGeAvT7xOk_IZeTrwDLiPMEJIvqqd6rb-t0SbUnaxUL3Hq_ZZ1tEFnZ3K8W0JFuJFKjoil8RO4TgyfVfZCrAxHkNI03NJ6miVcEAxkAyZN7Zkleu1jnZg5hT05KsZSGSgaBkAqsn49heMz3qkMTUaxZIi7J4Uam-nPbgEd04bmrUfOhOmckjMPmUYZ_QhrPFR2NpiGxmzuQ" } |
- To refresh a pair of tokens, the client sends a POST request to the /token path.
In the body of the request, the client specifies the following parameters:
- grant_type — to refresh the token, it is required that the refresh_token value must be specified for this parameter.
- refresh_token — the previously saved refresh token.
Request: POST https://uwin2012r2.n.local:9899/v1/Accounts/Token
Request Header: content-type: application/json
Request Body: grant_type=refresh_token&refresh_token=EVU7FlFLT2emhwfwnbwM-RiuD0oHjCIGTGeAvT7xOk_IZeTrwDLiPMEJIvqqd6rb-t0SbUnaxUL3Hq_ZZ1tEFnZ3K8W0JFuJFKjoil8RO4TgyfVfZCrAxHkNI03NJ6miVcEAxkAyZN7Zkleu1jnZg5hT05KsZSGSgaBkAqsn49heMz3qkMTUaxZIi7J4Uam-nPbgEd04bmrUfOhOmckjMPmUYZ_QhrPFR2NpiGxmzuQ |
- To log out, the client sends a POST request to the v1/Accounts/Logout path.
In the Authorization header, the client specifies currently valid access token in the Bearer <access_token> format.
Request: POST https://uwin2012r2.n.local:9899/v1/Accounts/Logout
Request Header: content-type: application/json Authorization: Bearer 908qldKH7ZZRfCqeWBNVVbnIM5UxisItP6gSnU_pZ5-qDenA5I2T0XvynyoELoEFmUUzm17_WuodIl1yRnneI15UzsgFnxlsHdhH9KQKFWKrR08PKRh-wL_NXj8PirXUa4PjK3Dx1pE-qCJh23FrrljIjsNjWeDFd63yY4j8ldyqP7fdx6bmp-hWwergK7va89AKEuYzIr_IQNir2yZMgVnXR-FqyEVw_xf_e3sFGJw |
The server sends a response in the following format.
Response body { "message": "Logout successful" } |
