Web

API Keys

When calling Ambience using the REST API, you need to logon first to obtain a token. You can do this via the REST API itself, but unless you choose https, your username and password are sent as plain text with the logon request.

As an alternative, you can create API keys - you just need to supply a elx.token=key parameter with your request.

An API Key is just a special kind of session key. An API Key represents a user and has the access rights of that user. There are two differences between API keys and session keys:

  1. API keys always start with [domain]:api-
  2. API keys are not automatically cleaned after a period of inactivity.

Creating an API Key

You can create an API Key for a user using the web admin panel. To create an API key:

  1. Click Add as shown:

    Figure 2.49. Add API Key

    Add API Key
  2. Select the user for whom you want to generate the API key. Click Save to generate and save the key.

    Figure 2.50. Generate API Key

    Generate API Key

    Figure 2.51. Generated API Key

    Generated API Key

You can either choose to create a separate user and assign an API Key to it and give it to several calling programs, or you can give each user program its own API Key.

Note the following important points about API Keys:

  1. API Keys have the access credentials of the user (and their groups) at the time of creation. If the user's groups are changed later, the API Key does not see this - just like group changes do not apply to the current session, but only from the next session. In the case of an API Key, there is only one long session for the life of the key. For this reason, the full Credentials of the API Key (user name followed by groups) are displayed as shown in Figure 2.51, “Generated API Key”.
  2. You cannot generate an API Key with administrator permissions because it gives too much control to anyone who gets such a key.
  3. There can be several API Keys for the same user. For example, there might be a user called "sales" with three API Keys for different partners, who embed each in a different program. If needed, you can turn any of them off by deleting the API Key without affecting the others.

Exporting API Keys

You can export and import API keys from the web interface. This makes it easy to move keys across servers.

To export all keys, click Export Keys.

Figure 2.52. Export API Keys

Export API Keys

The API is exported as a file in your home directory.

Figure 2.53. Exported API Keys

Exported API Keys

Importing API Keys

To import API keys, navigate to the Repository. You should see the exported API key files as shown in the following example.

Figure 2.54. API Keys List

API Keys List

To view the contents of a key file, click Open.

Figure 2.55. Open API Key

Open API Key

The contents of the API key file are then displayed.

Figure 2.56. API Key File Contents

API Key File Contents

You can either import the file from this page by clicking Import or go back to the Repository and import as follows.

Click a key file and select Import.

Figure 2.57. Import API Keys

Import API Keys

The system displays the number of API keys in the key file. Click Import to import the API keys.

Note

The system overwrites any existing key with the same token as the key being imported. Click Refresh to refresh the API list.

Viewing API Keys

Each user can view their API keys from Overview - Settings - Show API Keys.

Figure 2.58. View API Keys

View API Keys

CORS Support

Cross-origin resource sharing (CORS) is a mechanism that allows many resources on a web page to be requested from another domain outside the domain from which the resource originated.

Cross-Origin Resource sharing for DataSource APIs allows browser mash ups that merge data from different servers.

The following example demonstrates this feature.

  1. Start the Ambience Server and log in to the web interface.
  2. Open a new browser tab and navigate to this URL: http://localhost:8080/elx/do/eno/ds/ElixirSamples/DataSource/Excel.ds?mode=file
  3. Use a plugin like Live HTTP Headers to view the last response of the URL headers. The headers should be displayed as shown in the following example:

    Figure 2.59. Display URL Headers

    Display URL Headers
  4. Navigate to the Web tab under Admin, in the Ambience web interface. Enter a regular expression for Cross-Origin Resource Pattern, as shown. Click Save to save the pattern. Here, we enter .* as the pattern. This allows anyone to use our data on their web page.

    Figure 2.60. Add CORS Pattern

    Add CORS Pattern
  5. Click Clear Web Cache to clear the Ambience cache.
  6. Navigate again to the earlier URL: http://localhost:8080/elx/do/eno/ds/ElixirSamples/DataSource/Excel.ds?mode=file
  7. Check the last response of the URL headers. The headers should be displayed as shown in the following example:

    Figure 2.61. Display URL Headers After Adding CORS Pattern

    Display URL Headers After Adding CORS Pattern

    Note the Access-Control-Allow-Origin header. This tells us that CORS support is enabled and that we allow everyone to use our data.