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.
...
...
On this page:
...
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 |
...
: |
Response Headers
| 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>': |
Response Headers
| 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.
...
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- |
...
api.eis.utoronto.ca |
...
/v2 |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
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 |
...
| language | py |
|---|---|
| title | Response Body |
| collapse | true |
...
"Authorization: Bearer $VSS_API_TOKEN" curl -X GET -H "Authorization: Bearer $TK" https://vss- |
...
api.eis.utoronto.ca |
...
CURL
...
/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 |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
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 |
...
| language | py |
|---|---|
| title | Response Body |
| collapse | true |
...
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
} |