Veoci API Documentation

Authentication

GET /auth/token Deprecated

This method is deprecated and will be removed in future versions of this API.

User must be authenticated.

Input

Name	Data Type	Description
scope	String (allowed value = session)	If value = session, generate token that's good for 2 weeks and renews on every request. Optional. If not included, token will be valid for 60 seconds and will not renew.

Output

Name	Data Type	Description
token	String (32 characters)	Authentication token

Example Output

{"token":"aj2JKFs089c8saf5jsJ8J32jfExample"}

GET /auth/token/1.1

Requests a non-renewing authentication token with configurable duration. The client should track the expiration time and request a new token subsequent to its expiration.

The returned token is to be passed on subsequent API requests as the request header, X-Veoci-API-Auth. Example:

X-Veoci-API-Auth: aj2JKFs089c8saf5jsJ8J32jfExample

The client should authenticate to this endpoint using HTTP Basic authentication or a valid API authentication token (for renewals).

Input

Name	Data Type	Description
duration	Integer	Duration the requested API token should last, in seconds. Optional, defaults to 28800 (8 hours). Maximum value is 86400 (24 hours).

Output

Name	Data Type	Description
token	String (32 characters)	Authentication token
expires	Long	Expiration time, Java timestamp format (Unix timestamp * 1000 + milliseconds)
version	String	Token version. "1.1"

Example Output

{"token":"aj2JKFs089c8saf5jsJ8J32jfExample",expires:1452562143741,version:"1.1"}

DELETE /auth/token

Input

Name	Data Type	Description
token	String	API authentication token to destroy

Output

Name	Data Type	Description
status	String	success

Example Output

{"status":"success"}

GET /auth/logout OR GET /logout

Destroys the API user's current session credentials.

Input

Name	Data Type	Description
X-Veoci-API-Auth [request header]	String	API authentication token of current session

Output

Name	Data Type	Description
status	String	success

Example Output

{"status":"success"}

GET /auth/cas/finishLogin

Input

Name	Data Type	Description
appToken	String (>=32 characters)	App-generated token that was used at CAS login initiation. NOT the token generated by /auth/token.

Output

Name	Data Type	Description
casUsername	String	If status == (success\|unlinkedAccount), will contain the CAS username
casRealm	CasRealm	If status == (success\|unlinkedAccount), will contain the CAS realm
message	String	User-friendly description of authentication status
status	String	Status of validation. Possible values: (success\|unlinkedAccount\|expiredCredentials\|authFailure\|failure)
token	String (32 characters)	If status == success, authentication token to use for future api requests. See /auth/token.
token11	Token	If status == success, the full token object that would be returned by /auth/token/1.1, including expiration data
user	User	If status == success, same user object as /me

Example Output

Success

{
	message: "Authentication success.",
	casRealm: {
		id: 1,
		realm: "yale",
		serverUrl: "https://secure.its.yale.edu/cas",
		shortName: "CAS",
		description: "Yale University Central Authentication Service",
		orgName: "Yale University",
		dateModified: 1386176950000,
		logoutUrl: "https://secure.its.yale.edu/cas/logout"
	},
	token: "0uzoXuR6DMOXVkrxtYyfyDehvExample",
	token11: {
	   token: "0uzoXuR6DMOXVkrxtYyfyDehvExample",
	   expires: 1452562143741,
	   version: "1.1"
	}, 
	status: "success",
	casUsername: "aam26",
	user: {
		id: 1234,
		name: "example@user.com",
		[...]
	}
}

Unlinked Account

{
	message: "Your authentication was successful, but you need to link your Veoci account.",
	casRealm: {
		id: 1,
		realm: "yale",
		serverUrl: "https://secure.its.yale.edu/cas",
		shortName: "CAS",
		description: "Yale University Central Authentication Service",
		orgName: "Yale University",
		dateModified: 1386176950000,
		logoutUrl: "https://secure.its.yale.edu/cas/logout"
	},
	status: "unlinkedAccount",
	casUsername: "aam26"
}

Invalid/Expired Application Token

{
	message: "No CAS credentials found for requested application token. Please try again.",
	status: "authFailure"
}