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 request an access token using HTTPie and cURL

Examples

...

HTTPie

...

HTTPie

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

 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
Server:
nginx
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

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

...

cURL

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

Response Headers

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

{
  "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

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.

Response

HTTP/1.10 401 UNAUTHORIZED
Allow: POST, OPTIONS
ConnectionContent-Length: 115
keep-aliveContent-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.

Response

HTTP/1.0 401 UNAUTHORIZED
Allow: POST, OPTIONS
Content-Length: 103106
Content-Type: application/json
Date: Fri, 29 Apr 2016 1213:0455:42 GMT
Location: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 made to a given API endpoint via GET, POST, PUT, PATCH. 

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

http GET https://vss-api.eis.utoronto.ca/v2 "Authorization: Bearer $VSS_API_TOKEN"
curl -X GET -H "Authorization: Bearer $TK" https://vss-api.eis.utoronto.ca/v2

Basic Authentication

The second approach is using basic authentication as shown below:

http GET https://vss-wsapi.eis.utoronto.ca:8001/v2 -a $TK
curl -X GET https://vss-api.eis.utoronto.ca/v2 -u $TK

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

...

Response

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/auth/request-token

{
    "error": "unauthorizedauthentication error", 
    "message": "PleaseValid authenticatetoken, tobut gethas yourexpired. token.", 
    "status": 401
}

Username and password combination is not valid

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

...

Invalid Token

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

Response

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/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 by email or  or our contact form. contact form.

Response

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
}