Authentication Token Services - v1.4
Introduction
Authorization tokens are required when calling other Vexcel API services. The services in this document are used to generate, validate and terminate these authorization tokens. An authorization token is valid for 12 hours (24 hours for federated authenticated accounts) from creation and recorded in UTC time.
Login Service - Generates a new authorization token after validating the users' username/password.
Authenticate Service - Validates the expiration date/time of a user’s previously generated token.
Logout Service - Terminates a user’s previously generated token and active session.
Login Service
The Login Service receives username /password pairs and returns a new authorization token (or refreshes an existing token). The authorization token is returned both as a parameter called token (or AuthToken) and as an HTTP cookie named AuthToken1. The HTTP cookie can be useful for implicit API usage without repeatedly defining the authentication token. If the token or cookie is not present during other API requests, that request will fail, and an error will be returned. The Login Service only accepts POST requests.
This service is akin to getToken or requestToken as may be found with other API services.
Contact support@gic.org for credentials and reference Getting Started with the Vexcel Viewer for account setup.
Login Base URL:
This service will answer to requests on the following POST URL:
Base URL with all parameters defined as Key Value Pairs:
https://api.gic.org/auth/Login?username={username}&password={password}
RESTful parameters will continue to work for backwards compatibility. Key Value Pairs are recommended going forward.
Login Parameters:
Parameter | Parameter Type | Data Type | Description | Format | Notes |
|---|---|---|---|---|---|
Mandatory: | |||||
| Key Value Pair (KVP) | String | The user’s username |
|
|
| Key Value Pair | String | The user’s password |
|
|
Login Example:
https://api.gic.org/auth/Login?username={username}&password={password}
Login Successful:
{"token":{token}, "expiration_date": "2020-10-08T12:39:54"}Login Unsuccessful:
{"status": 701,"message": "Login Failed"}
Login Code Implementations:
|
|
|---|---|
cUrl | curl https://api.gic.org/auth/Login/ -d "username=<username>&password=<password>" |
Python | import requests
r = requests.post("https://api.gic.org/auth/Login/", data={'username': '<username>', 'password': '<password>'})
print(r.status_code, r.reason)
print (r.content) |
JavaScript | // ----------------------------------
// API : Login
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
var urlencoded = new URLSearchParams();
urlencoded.append("username", "usernameg");
urlencoded.append("password", "password");
var requestOptions = {
method: "POST",
headers: myHeaders,
body: urlencoded,
redirect: "follow"
};
fetch("https://api.gic.org/auth/Login", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log("error", error));
// ---------------------------------- |
Authenticate Service
The Authenticate Service receives an authentication token and returns the token’s expiration status. This is useful to check the validity of a token to see whether it is active or expired and if a new token must be issued with the Login Service.
Authenticate Base URL:
This service will answer to requests on following POST URLs:
Ordered as http REST parameters (mandatory parameters only):
https://api.gic.org/auth/Authenticate/{token}Base URL with parameters defined as a mix of REST and Key Value Pairs
https://api.gic.org/auth/Authenticate/{token}?format={format}Base URL with all parameters defined:
https://api.gic.org/auth/Authenticate/{token}?format={format}&jsopFunction={jsonpFunction}
Authenticate Parameters:
Parameter | Parameter Type | Data Type | Description | Format | Notes |
|---|---|---|---|---|---|
Mandatory: | |||||
| Ordered REST (1st) | String | The Authentication Token received from the Login Service. |
| |
Optional: | |||||
| Key Value Pair (KVP) | String | Format of the response.
|
|
|
| Key Value Pair | String | The customizable name of the padding function for |
| |
Authenticate Examples:
https://api.gic.org/auth/Authenticate?token={token}&format=json
Token Expired:
{"status": 403,"message": "Unauthorized"}Token Active:
{"status": 0,"message": "Success"}
https://api.gic.org/auth/Authenticate?token={token}&format=json&jsonpFormat=samplename
Token Expired:
function samplename() {return {"status": 403,"message": "Unauthorized"};}Token Active:
function samplename() {return {"status": 0,"message": "Success"};}
Logout Service
The Logout Service receives an authentication token and terminates that token and its active session. This is the same as allowing the token to expire, but forces termination prematurely. The primary use case of this service would be to terminate a token that is believed to have been compromised.
Logout Base URL:
This service will answer to requests on following POST URLs:
Ordered as http REST parameters (mandatory parameters only):
https://api.gic.org/auth/Logout/{token}
Logout Parameters:
Parameter | Parameter Type | Data Type | Description | Format | Notes |
|---|---|---|---|---|---|
Mandatory: | |||||
| Ordered REST (1st) | String | The Authentication Token received from the Login Service. |
| |
Logout Example:
https://api.gic.org/auth/Logout/{token}
Logout Successful:
{"status": 0,"message": "Success"}Logout Unsuccessful:
{"status": 403,"message": "Unauthorized"}(token already terminated or expired)
Need help? Create a support ticket | support@vexcelgroup.com