Getting a Token - web_services - 23.1

Spectrum Web Services Guide
Product type
Software
Portfolio
Integrate
Product family
Spectrum
Product
Spectrum > Web Services
Version
23.1
Language
English
Product name
Spectrum Technology Platform
Title
Spectrum Web Services Guide
First publish date
2007
Last updated
2024-10-17
Published on
2024-10-17T00:33:46.811413

To get a token, send a request to the TokenManagerService web service on the Spectrum Technology Platform server. You can access the TokenManagerService WSDL here:

http://server:port/security/TokenManagerService?wsdl

To get a token, send a request to the security web service on the Spectrum Technology Platform 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 Technology Platform user name and password in the request.

The TokenManagerService web service can issue two types of tokens.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 Technology Platform.

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 Technology Platform server.
port
The HTTP port used by Spectrum Technology Platform. 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"
}

TokenManagerService has two SOAP operations for getting a session token.

Operation Description

getAccessExpiringToken

Use this operation if you want to specify an expiration time for the token. Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessExpiringToken>
         <tokenLifeInMinutes>60</tokenLifeInMinutes>
      </tok:getAccessExpiringToken>
   </soapenv:Body>
</soapenv:Envelope>

The element <tokenLifeInMinutes> specifies the number of minutes until the token expires, also known as the token time-to-live. In this example the token will expire in 60 minutes.

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessExpiringTokenResponse
       xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <session>ebd7904b-07f6-15c9-82e4-71589131eb01</session>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..2pZB3qgpdC96xfOIPg9</token>
            <username>simon0897</username>
         </return>
      </ns2:getAccessExpiringTokenResponse>
   </soap:Body>
</soap:Envelope>

getAccessSessionToken

Use this operation if you want to get a token that will not expire. Note that the token will still become invalid if the session is inactive for 30 minutes, even if the token has not expired.

Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessSessionToken/>
   </soapenv:Body>
</soapenv:Envelope>

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessSessionTokenResponse
      xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <session>65822c9b-362e-2e0e-a02a-a50a1a761323</session>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..CEE-C1VjKTha</token>
            <username>simon0897</username>
         </return>
      </ns2:getAccessSessionTokenResponse>
   </soap:Body>
</soap:Envelope>

The response contains these elements:

access_token
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 Technology Platform 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 Technology Platform 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 Technology Platform server.
port
The HTTP port used by Spectrum Technology Platform. 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"
}

TokenManagerService has one SOAP operation for getting an open token.

Operation Description

getAccessToken

Use this operation to get an open token. Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessToken/>
   </soapenv:Body>
</soapenv:Envelope>

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessTokenResponse
      xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..f4JwHB4qPs0l</token>
            <username>paul1234</username>
         </return>
      </ns2:getAccessTokenResponse>
   </soap:Body>
</soap:Envelope>

The response contains these elements:

access_token
token
The security token.
username
The Spectrum Technology Platform 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.