API Site Configuration
Before using the Convio APIs each organization must follow a few simple steps to ensure proper security measures are in place. Please visit this page within the Convio Customer Center to find the detailed instructions.
Additionally, you must use an authentication token with many client-side calls to be sure that these API calls are being served by a trusted host, as discussed in more detail below. Server-to-server calls do not require a token.
Authentication Tokens
The Authentication Token is some secret that is associated with the user's session. Upon receiving and verifying the secret, the server knows that the request is coming from a page that can be trusted. There are two types of tokens available:
- S86 tag/WYSIWYG Component
- SSO Token
Using the Authentication Token when Creating a Page in Convio
When building your form in a Convio HTML editor, you can insert the Convio API: Authentication Token component from the Components drop-down menu (equivalent to the S86 tag). This component will be expanded to a hidden form element that will pass the correct token when the form is submitted. The value passed represents the "auth" parameter that is required for several client methods.
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. 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 Convio 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, several TeamRaiser API methods require the authentication token.
Note: Instead of using the WYSIWYG Components menu, you can also enter the tag directly using one of the following:
Bracket Syntax: [[S86]]
XHTML Syntax: <convio:session name="86"/>
When your requirements prohibit use of Convio's PageBuilder application, yet require use of the above methods, we recommend employing the following approach for non-Convio pages, or using the available server-side methods.
Using the Authentication Token when Creating a Page that is External to Convio
When creating a page in an outside application, you can use the getSingleSignOnToken server-side method to return a single sign-on "token" (SSO token) that can then be used in client-side requests to automatically log a user into the system.
This approach is appropriate in the case where a Web site external to Convio has authenticated the site visitor and wants to direct the user's browser to the Convio system and have them automatically logged in to the Convio system. The external web server, after verifying the identity of the visitor, calls this API method to get a token 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 limited time (typically, a few minutes).
Instead of using this token as the "auth" parameter, you should add this token as the "sso_auth_token" to any API request.
Making Server to Server Calls
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.
Calling the API from an Insecure Page
When calling the Convio API from an insecure page (a page not served via SSL) in Convio, the URL must be wrapped in a "T2" tag to add the "JservSessionId…" parameter. For example:
<form action="[[T2:https://secure2.convio.net/convio/site/CRConsAPI]]">
This tag ensures that the user's authenticated session information is transferred from the insecure server to the secure server.
Note: It is simpler for an administrator to build the page as a secure page (there is a check box in PageBuilder to make the page an SSL page). However, this may not always be feasible.
