All client APIs provide for specifying redirect URLs. As a result, AJAX is not needed to invoke the APIs. Luminate Online APIs can redirect after method execution to a specified URL, either on Luminate Online or on another system. The redirect, success_redirect and error_redirect parameters are optional parameters which can be passed on invocation of any client API.

Specifying a redirect parameter may result in a HTTP 302 "Redirect" status being returned to the client's browser following method invocation. The call may or may not have succeeded, depending on which parameter was used:

• success_redirect - redirects to the specified URL if the call succeeded
• error_redirect - redirects to the specified URL if the call failed
• redirect - redirects to the specified URL regardless of the result

The sign_redirects parameter is an optional boolean parameter, which, if true, instructs Luminate Online to sign redirects with a timestamp and the API secret key.

Using the sign_redirects Parameter

Using the sign_redirects option, the target can verify that a redirect request originated with Luminate Online. Otherwise it is impossible to trust that the page being served in response after an action is completed (e.g. a successful login or a completed donation) is being requested as a byproduct of completing that action or if it was just coming from any other source (e.g. a link or direct entry into the browser address bar).

The URL is signed by adding a timestamp to the query string. Then an MD5 or SHA-1 hash of the URL query string plus the CONVIO_API_SECRET_KEY are calculated and the result is appended to the query string. The CONVIO_API_SECRET_KEY should be a value that is not easily guessed and should never be stored or communicated in clear text. This is in direct contrast to the CONVIO_API_KEY, which can be communicated in clear text and is frequently visible in URLs or in the source code view of a web page.

1. Pull that portion of the URL query string after the "?" and up to the argument "&signature=".
2. Append the secret key to that portion of the query string.
3. Generate the appropriate hash (MD5 or SHA-1) for that string.
4. Compare the hash with the value of the "signature" argument.
5. Assuming that the values match, you can be confident that the URL was generated by Luminate Online.
6. Compare the value of the "ts" argument in the URL with the current time from your system in seconds since 1/1/1970. The values should be close enough (within a few seconds provided your system clock is accurate) to ensure that this is not a replay attack.

Automatic Redirection Via Insecure Channel

When a redirect is specified to an external domain, the API will first check to see if it has already pushed a session cookie on the insecure channel. If not, it will actually generate 2 consecutive redirects to ensure that the session cookie is passed on the insecure channel.

This is particularly important in single-sign-on implementations to ensure that links from the partner system connect back to the same session that authenticated the user originally.

Substitution of Request Params in Redirect URLs

Request parameters can be substituted into the redirect URL by specifying as the value of a query string parameter in the URL. This functionality is useful for redisplaying the data that was entered by the user.

For security reasons, some parameters are never passed in a redirect URL. These include:

• card_number
• cvv_number
• card_exp_month
• card_exp_year
• password
• user_password
• retype_password
• old_password
• user_name
• token
• sso_auth_token
• login_name
• login_password

Substitution of Response Elements in Redirect URLs

Any value that would normally be returned in the response XML can be substituted into the redirect URL. The response values use XPath syntax to identify the value from the response XML (for example, error_code=). This feature is necessary for error handling, displaying confirmation codes, and retrieving cons_id from the return. Because the response is a structured XML document, you may use XPath syntax for accessing the variables from the response.

Typically, the response documents are fairly simple and the path used to access a variable will be a simple directory path.