Getting a Token

To get a token, send a request to the security web service on the Spectrum OnDemand server. You can access the security WADL here:

http://server:port/security/rest?_wadl

This web service uses Basic authentication so you must include a valid Spectrum OnDemand user name and password in the request.

The security web service can issue two types of tokens. The token types are:

  • Session token
  • Open token

Getting a Session Token

A session token is tied to a user session and can only be used by the computer that requested the token. Since it is tied to a session, the token will become invalid if the session is inactive for 30 minutes. A session token is the most secure type of token and is the recommended token type to use to authenticate to Spectrum OnDemand.

To get a session token, use this URL:

http://server:port/security/rest/token/access/session/ttlInMinutes

Where:

server
The host name or IP address of your Spectrum OnDemand server.
port
The HTTP port used by Spectrum OnDemand. By default this is 8080.
ttlInMinutes
The number of minutes until the token expires, also known as the token time-to-live. If you do not want the token to expire, specify 0.

Here is a sample response:

{
   "access_token": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..ESnq4JNEBbVMKycd139z0w.NFXAskVY0seX",
   "session": "09aa1fbb-71j3-43c7-ab8c-d800214283d4",
   "username": "admin"
}

The response contains these elements:

access_token
The security token.
session
The session ID of the session that the token is tied to. The token will only be accepted if this session ID is included in the request. If running with a JavaScript application, you must include a withCredentials: true web request header to ensure the session ID is passed back and forth on all requests.
username
The Spectrum OnDemand user name used to obtain the token. The user name is returned for informational purposes only and is not needed when you use the token.

Getting an Open Token

An open token is not tied to either a user or a specific computer. It is the least-secure token type.

Important: Avoid using open tokens that do not expire. If an open token is obtained by an unauthorized third party, the token could be used indefinitely, and from any computer, to gain access to your Spectrum OnDemand server.

To get an open token, use this URL:

http://server:port/security/rest/token/access/ttlInMinutes

Where:

server
The host name or IP address of your Spectrum OnDemand server.
port
The HTTP port used by Spectrum OnDemand. By default this is 8080.
ttlInMinutes
The number of minutes until the token expires, also known as the token time-to-live. If you do not want the token to expire, specify 0.

Here is a sample response:

{
   "access_token": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..fI",
   "username": "admin"
}

The response contains these elements:

access_token
The security token.
username
The Spectrum OnDemand user name used to obtain the token. The user name is returned for informational purposes only and is not needed when you use the token.