Introduction

The API requires a token sent on each request via the the Authorization header header to authenticate. This This token can can be obtained by making a a POST request request to the URI /auth/request-token where where you 'll would include your your VSKEY credentials credentials using the Authorization Header.

...

.

Request Access Token

This section shows how to to request an access token using using HTTPie and CURL.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-wsapi.eis.utoronto.ca:8001/auth/request-token -a <username> http: password for <username>@vss-wsapi.eis.utoronto.ca:8001:

Response Headers

Code Block

language	py
title	Response Headers
collapse	true

 HTTP/1.1 200 OK
Allow: POST, OPTIONS
Connection: keep-alive
Content-Length: 179
Content-Type: application/json
Date: Fri, 29 Apr 2016 11:52:47 GMT
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1461930780

Response Body

Code Block

language	py
title	Response Body
collapse	true

{

   "duration": 86400,
  "exp": <expiry_time>,
  "tokenexp_date": "<token_here><timestamp>",
  "token": "<token>",
  "usertype": "<username>ACCESS"
}

...

cURL

Code Block
curl -X POST https://vss-wsapi.eis.utoronto.ca:8001/auth/request-token -u <username> <username>EnterEnter host password for user '<username>':

Response Headers

Code Block

language	py
title	Response Headers
collapse	true

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 29 Apr 2016 12:00:20 GMT
Content-Type: application/json
Content-Length: 179
Connection: keep-alive
X-RateLimit-Remaining: 4
X-RateLimit-Limit: 5
X-RateLimit-Reset: 1461931230
Allow: POST, OPTIONS
Strict-Transport-Security: max-age=63072000
X-Frame-Options: DENY
X-Content-Type-Options: nosniff

Response Body

Code Block

language	py
title	Response Body
collapse	true

{
  "duration": 86400,
  "exp": <expiry_time>,
  "exp_date": "<timestamp>",
  "token": "<token_here><token>", 
  "usertype": "<username>ACCESS"
}⏎

Unauthorized

Getting a 401 Unauthorized error as shown below when requesting a new access token, could be due to the following reasons:

...

Response

collapse

Code Block
true	HTTP/1.1 401 UNAUTHORIZED

...

Re-initializing your VSKEY credentials is strongly advised. To do so, please follow this KB Article.

...

Response

true

collapse

Code Block

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
}

...

Contacting the VSS Team to request access is advised by email or our contact form.

...

Response

true

collapse

Code Block

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
}

...

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 made to any a given 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:

There are two separate approaches to authenticate using OAuth: Bearer Authorization Header and Basic Authentication described in the following sections:

Bearer Authorization Header

The first approach is sending a bearer authorization header within your request, which will authorize the request from the header section. The following examples illustrate how to pass the Authorization header with CURL and HTTPie

Code Block
http GET https://vss-wsapi.eis.utoronto.ca:8001/v2 -a $TK

Code Block

language	py
title	Response Headers
collapse	true

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Fri, 29 Apr 2016 14:11:09 GMT
Strict-Transport-Security: max-age=63072000
Transfer-Encoding: chunked
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1461942000

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": ""Authorization: Bearer $VSS_API_TOKEN"
curl -X GET -H "Authorization: Bearer $TK" https://vss-ws.eis.utoronto.ca:8001/v2/inventory/", 
        "iso": "https://vss-ws.api.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 /v2

Basic Authentication

The second approach is using basic authentication as shown below:

Code Block
http GET https://vss-wsapi.eis.utoronto.ca:8001/v2 -ua $TK

Code Block

language	py
title	Response Headers
collapse	true

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Fri, 29 Apr 2016 14:11:09 GMT
Strict-Transport-Security: max-age=63072000
Transfer-Encoding: chunked
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1461942000

Code Block

language	py
title	Response Body
collapse	true

{
  "meta": {
    "user": "jm", 
    "time": "0.00341s"
  }, 
  "_links": {
    "status": "
curl -X GET https://vss-wsapi.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/"
  }
}⏎             -u $TK

Unauthorized

Getting a 401 Unauthorized error as shown below when using an access token, could be due to the following reasons:

...

Generate a new token as previously described /auth/request-token

...

Response

true

collapse

Code Block

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
}

...

Either a typo or something at our end went wrong. Just generate a new access token at /auth/request-token

...

Response

true

collapse

Code Block

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
}

...

Contacting the VSS Team to request or restore access is advised by email or our contact form.

...

Response

true

collapse

Code Block

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
}

...

Versions Compared

Old Version 5

New Version Current

Key

Table of Contents

Introduction

Request Access Token

HTTPie

Response Headers

Response Body

cURL

Response Headers

Response Body

Unauthorized

Response

Response

Response

HTTPie

Bearer Authorization Header

CURL

Basic Authentication

Unauthorized

Response

Response

Response

Page Comparison

Versions Compared

Old Version 5

New Version Current

Key

Table of Contents

Introduction

Request Access Token

HTTPie

Response Headers

Response Body

cURL

Response Headers

Response Body

Unauthorized

Response

Response

Response

HTTPie

Bearer Authorization Header

CURL

Basic Authentication

Unauthorized

Response

Response

Response