Token Request Service Specification
Token Request Service Specification🔗
Description:🔗
The token request service must be part of the integrating application and should follow this specification.
- An HTTP GET service that accepts URL parameters as input and produces JSON/JSONP as output.
The output depends on the domain of the application. The domain of an application is a combination of protocol, hostname and port in the URL (e.g. http://www.myapp.com:8080/) If the integrating application and Search! are on different domains, then the Ajax request will automatically be converted from a JSON to a JSONP request. This can be detected by the availability of the callback URL parameter.
Upon receiving the token request, the service must call the SOAP Authentication service of Search! to get a token (see section Authentication service). The integrating application must provide an environment, password and roles. It can either choose the environment itself or use the value passed as parameter.
On error the token request service should include a text message or code explaining the cause. When using JSON the HTTP status code should be a 4xx or 5xx code depending on the cause. When using JSONP the HTTP status code should always be 200 also in case of error otherwise the message is lost.
To signal that the user is not logged in or the session has expired, return an error code SESSION_TIMEOUT as follows:
{"errorCode": "SESSION_TIMEOUT", "message": "User not logged in"}
A SESSION_TIMEOUT will redirect the user to the login page if configured. The same effect can be achieved by returning HTTP status code 401 (only on JSON, not JSONP).
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| cookie | HTTP Header | (implicit) the cookie of the integrating application used to recognize the user |
| environment | string | (optional) Search! environment to request access for. Taken from the URL parameter of Search! |
| externalToken | string | (optional) a token obtained from the integration application used to recognize the user. Taken from the URL parameter of Search! |
| callback | string | Name of the JavaScript handler for the cross-domain request (cross-domain only) |
Returns🔗
| Result format | Type | Description |
|---|---|---|
| "token" | JSON | Access token as a quoted string if request parameter callback is omitted (same domain only) |
| callback("token") | JSONP | Access token as a quoted string within a function call, if request parameter callback is given (cross-domain only). |
Pre-Condition🔗
The user must be logged-in on the integrating application and have received a cookie.
Post-Condition🔗
- On success, a token has been created in Search! for subsequent calls to the Ajax search service.
- On SESSION_TIMEOUT error, the user is redirected to the loginPageUrl (if configured).