An authentication token is a piece of information that is generated by the Luminate Online server and passed via a known secure channel that can then be echoed back as part of an HTTP request to verify the authenticity of the caller.
An authentication token is required for any client API that accesses personal data about a constituent that is not publicly visible. The authentication token is required because reliance on only a session cookie to establish the identity of the caller could potentially open the APIs to cross-site request forgeries. This extra level of security ensures that a constituent's personal data cannot be accessed or modified by code running on a malicious site.
There are two types of tokens that can be used for this form of authentication. The first is an information-less token that is stored in the user's session. This can be rendered in content pages using the [[S86]] session tag, or can be accessed from a trusted domain via the JavaScript API. This token must be sent back to the same user session that created it in order to authenticate the request. The second is a single-sign-on or SSO token. This token is generated by the system and passed back via a server-side API call that is secure by virtue of IP address white-listing. This token is associated with a particular constituent and can be sent to an anonymous session in order to log in as that constituent, but it cannot be passed as part of the URL. If you wish to use the SSO token, then you must pass it in the body of a POST request.
When building a form on a Luminate Online web site in PageBuilder, you can insert the "Luminate Online API: Authentication Token" component from the Components drop-down menu. This component is equivalent to the S86 tag in the page HTML source. The component or tag will be expanded to a hidden form element that will generate and pass the correct token when the form is submitted.
If you use scripting to send the request instead of form submission, your script must get the token value from the hidden field and submit it with API calls using the parameter name auth. You can also render just the value of the token (as opposed to the entire hidden input element) by using the tag [[S86:true]]. In this example, "true" is the value of the "token only" flag, indicating that only the token value should be rendered. Although the token is visible when viewing the page source, it adds security because it is temporary and not valid for any other user.
Applying this authentication token from a Luminate Online hosted and trusted page ensures the most secure and reliable experience for your constituents. This component must be included in the following Web Client calls:
In addition, most TeamRaiser API methods require the authentication token.
[[S86]]
<convio:session name="86"/>
When creating a page in an outside application, you can use the SRConsAPI:getSingleSignOnToken server-side method to return both a single sign-on "token" (SSO token) and nonce and rouding id that can then be used in client-side requests to automatically log a user into the system. The SSO token can be used in multiple API calls, but is only valid as a POST parameter, not as part of the URL. The nonce token is for one-time use, but can be passed in a URL to automatically connect the user to a logged-in session. The routing id is passed as the jsessionid path parameter when using the nonce, to ensure the request is sent to the correct load balancing server.
This approach is appropriate in the case where a Web site external to Luminate Online has authenticated the site visitor and wants to direct the user's browser to the Luminate Online system and have them automatically logged in. The external web server, after verifying the identity of the visitor, calls SRConsAPI:getSingleSignOnToken to get a nonce that will authenticate the source of the request when sent by the visitor's browser in a subsequent HTTP request. This token is only valid for the specific user and only for a single use. The SSO token can be passed to any API POST request in the sso_auth_token parameter. The nonce should be passed in a URL that the user is redirected or sent to via a link, and should be passed in the NONCE_TOKEN GET parameter.
Server-to-server calls do not require authentication tokens because you must enter the IP addresses of the external sites that you will permit to make calls when you set up your site for API access.
<form action="[[T2:https://secure2.convio.net/organization/site/CRConsAPI]]">
This tag ensures that the user's authenticated session information is transferred from the insecure server to the secure server.