Token Resource

The Token resource has been provided so the API can generate a specific user token that grants access to content for a specific keycode; this is passed as a parameter within the request. The Surpass player can then use this token to integrate with the Surpass internal service to display the view responses functionality that is available in the Audit screen; the ultimate goal of this is to display the responses in an external system. To call this method, the user specified within the request must have a specific permission which is not available within the UI.

Token Resource

Below we have listed the operations, HTTP verbs and an example URL for the Token resource within the Surpass API.
Operation HTTP Verb Example URL
Create POST https://...surpass.com/api/v2/Token
Attributes for the Token Resource

Within the table below we have provided all of the attributes included in the token resource. This includes the attribute name, data type and if the attribute is mandatory when sending a POST request. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET) Unique Identifier Mandatory for Create (POST)
Keycode String Unable to GET/PUT/DELETE N/A N/A N/A N/A Allows to create a SecureAssess token for a specific keycode.
Additional Notes
  • The keycode passed into the request must be in a finished state.


POST Request and Return

The POST Token method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.
Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.

Example POST request & response (JSON)
Example POST request & response (XML)


Required Permissions

To successfully call the POST Token method, the user specified in the header of the request must have the 'Create Keycode Token' permission in Surpass. This permission is not available within the UI, please speak to your BTL Account Manager, if you would like to integrate with this method.

Feedback and Knowledge Base