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 would include your VSKEY credentials using the Authorization Header.
Request Access Token
This section shows how to request an access token using HTTPie and 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-api.eis.utoronto.ca/auth/request-token -a <username>
http: password for <username>@vss-api.eis.utoronto.ca: |
| Code Block |
|---|
|
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 |
|---|
|
{
"duration": 86400,
"exp": <expiry_time>,
"exp_date": "<timestamp>",
"token": "<token>",
"type": "ACCESS"
} |
cURL
| Code Block |
|---|
curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>
Enter host password for user '<username>': |
| Code Block |
|---|
|
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 |
|---|
|
{
"duration": 86400,
"exp": <expiry_time>,
"exp_date": "<timestamp>",
"token": "<token>",
"type": "ACCESS"
} |
Unauthorized
Getting a 401 Unauthorized error as shown below when requesting a new access token, could be due to the following reasons:
Response
| Code Block |
|---|
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
| 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
} |
User is not permitted to access the API
Contacting the VSS Team to request access is advised by email or our contact form.
Response
| 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
} |
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:
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-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:
| Code Block |
|---|
http GET https://vss-api.eis.utoronto.ca/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
| 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/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
Response
| 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/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.
Response
| 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
} |