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

Parameter

Parameter Type

Data Type

Description

Format

Notes

Mandatory:

username

Key Value Pair (KVP)

String

The user’s username

username=john.doe

 

password

Key Value Pair

String

The user’s password

password=secret

 

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

Parameter

Parameter Type

Data Type

Description

Format

Notes

Mandatory:

token

Ordered REST (1st)

String

The Authentication Token received from the Login Service.

/{token}

Optional:

format

Key Value Pair (KVP)

String

Format of the response.

json - JavaScript Object Notation

jsonp - JavaScript Object Notation with Padding

format=json

 

jsonpFunction

Key Value Pair

String

The customizable name of the padding function for format=jsonp calls. If left undefined, the default function name is VexcelFunction.

jsonpFunction={CustomName}

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

Parameter

Parameter Type

Data Type

Description

Format

Notes

Mandatory:

token

Ordered REST (1st)

String

The Authentication Token received from the Login Service.

/{token}

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)


External Resources

 

Need help? Create a support ticket | support@vexcelgroup.com