Overview

Before you can use Luminate Online APIs, you must configure your site to enable and control API access. The Open API Configuration tool allows site administrators to configure your site for API access. The Open API Configuration tool is also used to manage cross-domain access to the Open APIs from JavaScript clients, and allows logging of Open API calls and downloading/viewing of log files.

Luminate Online APIs permit clients to integrate features and functionality of the Luminate Online platform into other web server applications or web page content. These APIs can be divided into two different categories based on how they are accessed. Each offers slightly different features and has different configuration requirements. These categories are:

• Client APIs: APIs intended to be accessed directly from a constituent's web browser using client-side scripting. These APIs are the easiest to use, requiring no server-side programming. They may or may not require authentication or session security, depending on the information they expose.
• Server APIs: APIs for use by other application servers. Some may be used as server-side proxies for the Client APIs described above. These APIs respond only to secure requests from trusted IP addresses, and require valid API Administrator credentials with each request. As such, they are able to expose some administrative functions.

The Open API Configuration tool allows a site administrator to easily configure access for both categories of Luminate Online APIs, and also for Luminate Online Web Services.

Accessing the Open API Configuration Tool

To access the Open API Configuration tool:

1. Log in to Luminate Online as an administrator.
2. Go to Setup->Site Options.
3. Click the Open API Configuration tab.

A dashboard screen will open showing the configuration status of the various API options. Some of these may be configured automatically by the Open API Configuration tool. Configured options appear in green next to a check mark, while options that are not yet configured appear in red beside an "X." Note: Not all options must be configured for all API access methods.

The sections of the dashboard correspond generally to different access methods. Edit the settings for each section by clicking the link next to the section heading. The sections available are:

• Configure API Keys --Configures the site for either client-side or server-side API access. Note: To use server-side REST-style APIs, you must also define the options under the Configure API to allow server access section. 
• Configure API to allow server access -- Use this section to list the addresses of servers authorized to access the Luminate Online APIs (Server), and to create API Administrator accounts to control access via Luminate Online APIs (Server) and Luminate Online Web Services.
• Configure JavaScript to Open APIs -- Use this section to control cross-domain access from web pages hosted on other domains that reference Luminate Online's cross-domain policy files (crossdomain.xml).
• Configure AJAX proxy service -- Use this section to designate external domains to which Luminate Online may proxy AJAX JavaScript requests.
• Configure Web Services -- Use this section to configure the Luminate Online Web Services SOAP-protocol APIs. For additional information on Luminate Online Web Services, see the Luminate Online Web Services website.

Click the corresponding Edit action link on the main Open API Configuration page to access and configure your site for use with the APIs.

Open API Keys

These API keys must be configured to allow access through any of the REST-style Luminate Online APIs (Client) or Luminate Online APIs (Server). API Key is the only required field, it may be entered or changed to a different value here. The other available options are:

• API Key -- This key is an arbitrary value that must be passed as the value of the api_key parameter when invoking Luminate Online APIs either from a server script or web form. This is not a secure password and it may be included in a hidden field of a web form. Note: Certain special characters in the API Key will cause in an "Incorrect API key" error during use. Avoid using these characters: & : \ " ' ? = 
• API Secret Key -- This key is an arbitrary value that will be used by Luminate Online APIs to sign responses. This key should never be passed in API requests directly and should be a reasonably complex string. It is used by the Luminate Online server along with additional data to generate a hash signature on redirect responses to API calls when the sign_redirects parameter is set. For additional information on its use, see Using Redirect URLs
• Generate a new Secret Key -- If the value of your secret key has been compromised, click this button to generate a new one.
• Digital signature encryption algorithm -- Determines the encryption method when the option to sign_redirects is used with API calls. The default is MD5, but SHA-1 offers a more secure encryption algorithm.
• Single Sign-On APIs -- Check this box to enable singleSignOn, which allow a trusted external host to log in a constituent using a token returned by getSingleSignOnToken. Clearing this check box disables the singleSignOn method of the SSO API. For additional information see Single Sign On (Luminate Online as client).

Open API Server API Configuration

This screen allows site administrators to designate which external systems have access to Server APIs by adding them to the IP White List.

Note: The IP White List only permits access to the Luminate Online API (Server) REST-style interfaces. Luminate Online Web Services SOAP APIs use a different IP White List, and Luminate Online API (Client) interfaces allow connections from any IP.

The available options are:

• Add New IP Range to List -- Specify the IP Range for servers authorized to access the Open API (Server) interfaces using CIDR notation.
• Add Current IP Address to list -- This button automatically adds the IP address of the system on which you are running the Luminate Online Admin application to the White List. This can be useful for testing.
• Remove Selected IP Range -- This button removes selected server IP ranges from the White list.
• API Administrative Accounts -- Set up accounts used by both the Open API (Server) REST-style APIs and the Luminate Online Web Services SOAP APIs. API Administrator Account credentials must be passed in the login_name and login_password parameters on Server API calls; they are not used by Client API calls. For more information see API Administrator Accounts for Server API Access.

JavaScript Configuration

Use this page to control cross-domain JavaScript access from pages you host on other domains. You can grant different levels of access (basic or trusted) to different domains.

Options on this page are:

• Allow JavaScript API from these domains -- List any external domains which should have basic access. These domains will be able to create constituents (but not update) and retrieve public data. The list should be comma separated and can include wildcards (e.g. *.convio.com).
• Trust JavaScript API from these domains -- List any external domains which should have trusted access. Scripts hosted from these domains will be able to retrieve an authorization token for use with the Luminate Online APIs. Trusted domains will be able to retrieve personal information about constituents and update constituent data.

These settings apply only to JavaScript access to Luminate Online APIs (Client). They do not apply Server APIs or to Luminate Online Web Services.

AJAX Proxy Configuration

Use this page to designate other domains from which services may be proxied through the Luminate Online web server.

Options on this page are:

• AJAX Proxy Allowed Domains -- Use this field to specify a list of domains to which Luminate Online may proxy AJAX requests.
• Forward cookies -- Set this flag to forward cookies to proxied services (note restrictions).
• Pass arguments through template rendering -- Set this flag to accept Luminate Online template expressions as tags in script requests from clients and render them before passing the result to the proxied service.
• Maximum input body length in MBytes -- Use this value to limit the size of the request that Luminate Online will pass to the proxied service.

Configuring or Viewing API Logs

Use the Configure or View API logs page, located under "Related Actions," to enable various levels of logging for debugging and trouble-shooting purposes and to view the generated log files. One file is maintained for each instance of the Luminate Online web server running for any given site (one for each JVM).

API Logging Level -- Controls what requests and responses are logged:

• OFF (no logging)
• ERROR (log only errors)
• INFO (log request parameters and responses)
• DEBUG (most detailed logging)

For performance reasons, INFO and DEBUG logging are typically used only in development and debugging, whereas ERROR logging or OFF may be used in day-to-day operation. Log file size is limited to a 1MB file with one backup (2MB total log size per site, per JVM), to guard against a potential out-of-memory condition in the event that logging is accidentally left on.