Table of Contents
Introduction
The API requires a token sent on each request via the Authorization header to authenticate. This token can be obtained by making a POST request to the URI /auth/request-token where you'll include your VSKEY credentials using the Authorization Header.
| Warning |
|---|
The EIS Virtual Cloud RESTful API is currently in BETA. If you are a current customer and would like to join through this period, please refer to the following KB Article. |
Request Access Token
This section shows how to request an access token using HTTPie and RESTful API - Authentication CURL.
| Note |
|---|
Authentication tokens are valid for 24 hours (86,400 sec). After this period, a new token must be requested. |
HTTPie
| Code Block |
|---|
http POST https://vss-ws.eis.utoronto.ca:8001/auth/request-token -a <username>
http: password for <username>@vss-ws.eis.utoronto.ca:8001: |
...
| Code Block |
|---|
| language | py |
|---|
| title | Response Body |
|---|
| collapse | true |
|---|
|
{
"duration": 86400,
"token": "<token_here>",
"user": "<username>"
} |
CURL
| Code Block |
|---|
curl -X POST https://vss-ws.eis.utoronto.ca:8001/auth/request-token -u <username>Enter host password for user '<username>': |
...
| Code Block |
|---|
| language | py |
|---|
| title | Response Body |
|---|
| collapse | true |
|---|
|
{
"duration": 86400,
"token": "<token_here>",
"user": "<username>"
}⏎ |
Unauthorized
Getting a 401 Unauthorized error as shown below when requesting a new access token, could be due to the following reasons:
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
HTTP/1.1 401 UNAUTHORIZED |
Username and password combination is not valid
Re-initializing your VSKEY credentials is strongly advised. To do so, please follow this KB Article.
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
HTTP/1.0 401 UNAUTHORIZED
Allow: POST, OPTIONS
Content-Length: 115
Content-Type: application/json
Date: Fri, 29 Apr 2016 13:55:25 GMT
{
"error": "authentication error",
"message": "Invalid username and password combination.",
"status": 401
} |
User is not permitted to access the API
Contacting the VSS Team to request access is advised by email or our contact form.
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
HTTP/1.0 401 UNAUTHORIZED
Allow: POST, OPTIONS
Content-Length: 106
Content-Type: application/json
Date: Fri, 29 Apr 2016 13:55:51 GMT
{
"error": "authentication error",
"message": "User is not authorized to access.",
"status": 401
} |
Using Access Token
At this point you have already generated an access token to use the API valid for a certain period of time. Now, this token can be used for every request sent to any API endpoint via GET, POST, PUT, PATCH. The OPTIONS method does not require the Authorization Header.
Using your access token is quite simple and you have a few options depending the tool you use. In this section we will demonstrate how to use the access token with HTTPie and CURL:
HTTPie
Assuming there's been set the access token value in the environment variable TK, you can make a simple get request to the /v2 resource:
...
| Code Block |
|---|
| language | py |
|---|
| title | Response Body |
|---|
| collapse | true |
|---|
|
{
"_links": {
"domain": "https://vss-ws.eis.utoronto.ca:8001/v2/domain/",
"folder:": "https://vss-ws.eis.utoronto.ca:8001/v2/folder/",
"image": "https://vss-ws.eis.utoronto.ca:8001/v2/image/",
"inventory": "https://vss-ws.eis.utoronto.ca:8001/v2/inventory/",
"iso": "https://vss-ws.eis.utoronto.ca:8001/v2/iso/",
"network": "https://vss-ws.eis.utoronto.ca:8001/v2/network/",
"os": "https://vss-ws.eis.utoronto.ca:8001/v2/os/",
"request": "https://vss-ws.eis.utoronto.ca:8001/v2/request/",
"session": "https://vss-ws.eis.utoronto.ca:8001/v2/session/",
"status": "https://vss-ws.eis.utoronto.ca:8001/v2/status/",
"template": "https://vss-ws.eis.utoronto.ca:8001/v2/template/",
"version": "https://vss-ws.eis.utoronto.ca:8001/v2/version/",
"vm": "https://vss-ws.eis.utoronto.ca:8001/v2/vm/"
},
"meta": {
"time": "0.00341s",
"user": "jm"
}
} |
CURL
| Code Block |
|---|
curl -X GET https://vss-ws.eis.utoronto.ca:8001/v2 -u $TK |
...
| Code Block |
|---|
| language | py |
|---|
| title | Response Body |
|---|
| collapse | true |
|---|
|
{
"meta": {
"user": "jm",
"time": "0.00341s"
},
"_links": {
"status": "https://vss-ws.eis.utoronto.ca:8001/v2/status/",
"domain": "https://vss-ws.eis.utoronto.ca:8001/v2/domain/",
"network": "https://vss-ws.eis.utoronto.ca:8001/v2/network/",
"folder:": "https://vss-ws.eis.utoronto.ca:8001/v2/folder/",
"image": "https://vss-ws.eis.utoronto.ca:8001/v2/image/",
"request": "https://vss-ws.eis.utoronto.ca:8001/v2/request/",
"vm": "https://vss-ws.eis.utoronto.ca:8001/v2/vm/",
"session": "https://vss-ws.eis.utoronto.ca:8001/v2/session/",
"iso": "https://vss-ws.eis.utoronto.ca:8001/v2/iso/",
"inventory": "https://vss-ws.eis.utoronto.ca:8001/v2/inventory/",
"version": "https://vss-ws.eis.utoronto.ca:8001/v2/version/",
"os": "https://vss-ws.eis.utoronto.ca:8001/v2/os/",
"template": "https://vss-ws.eis.utoronto.ca:8001/v2/template/"
}
}⏎ |
Unauthorized
Getting a 401 Unauthorized error as shown below when using an access token, could be due to the following reasons:
Expired Token
Generate a new token as previously described /auth/request-token
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
HTTP/1.0 401 UNAUTHORIZED
Allow: HEAD, OPTIONS, GET
Content-Length: 103
Content-Type: application/json
Date: Fri, 29 Apr 2016 14:19:39 GMT
Location: https://vss-api.eis.utoronto.ca:8001/auth/request-token
{
"error": "authentication error",
"message": "Valid token, but has expired. ",
"status": 401
}
|
Invalid Token
Either a typo or something at our end went wrong. Just generate a new access token at /auth/request-token
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
HTTP/1.0 401 UNAUTHORIZED
Allow: HEAD, OPTIONS, GET
Content-Length: 103
Content-Type: application/json
Date: Fri, 29 Apr 2016 14:19:39 GMT
Location: https://vss-api.eis.utoronto.ca:8001/auth/request-token
{
"error": "authentication error",
"message": "Invalid token.",
"status": 401
} |
User is no longer authorized to access the API
Contacting the VSS Team to request or restore access is advised by email or our contact form.
...