API key security provider in Jitterbit App Builder

The API Key security provider allows administrators to secure App Builder REST APIs using an API key code generated by App Builder. The consumer passes the API key to App Builder when making REST API requests. Because each API key is associated with an individual user, this provides both authentication and authorization.

Definition and use cases

App Builder's API keys consist of a 128-bit, cryptographically random number. The keys are base64url encoded. Below is an example of an API key:

DLOo9sPS5slJEMHpXBFt3g

API keys have the following advantages over standard username/password authentication:

• They have greater entropy than username-password combinations.
• They can survive a password reset.
• They can be easily revoked.
• They can be rotated.
• They are faster. Passwords must be hashed, which is deliberately slow.

The disadvantages, or weaknesses, of API keys include managing their distribution and the risk of leaks. Some of the use cases where API keys can be the most adequate authentication method include:

• Service-level accounts
• Application-to-application communication
• Server-to-server communication
• Read-only access
• Non-sensitive information

Add an API key

To add a new API key, go to IDE > Security Providers.

The Security page will be shown, where the User Authentication table will display all current user authentication methods. If there aren't any API keys or if you want to create a new one, click the + User Authentication button. The Provider dialog will come up, containing the following fields:

1. Under the Settings section:

   1. Name: Enter a name to identify your API key.

   2. Type: In the dropdown menu, select API Key as the type of security provider you're creating. Doing this will alter the rest of the fields that are shown in the dialog.

   3. Priority: Enter a number to set the order in which security providers appear on the login form.

   4. Enabled: Click this checkbox to activate your API key.

   5. Identifier: This field is automatically generated by App Builder.

2. Under the Keys section:

   1. Default Expiry: Enter how many minutes for the default lifetime of new keys. (Altering this field does not affect existing keys.)

   2. Max Expiry: Enter how many minutes for the maximum lifetime of new keys. (Altering this field does not affect existing keys.)

   3. Length: Enter the length (in bytes) of new keys. (Altering this field does not affect existing keys.)

When you're done, click Save. If you want to exit without saving, click Cancel. After you save a new API key, you will be taken back to the Security page, where the User Authentication table will show the new API key you've just created. By clicking the icon at the end of its row, you can continue configuring it.

Configure an API key

To configure an API key, go to IDE > Security Providers. Locate the API key you want to edit in the User Authentication table and click the icon at the end of its row. The Provider page will be shown, where you can add additional configurations. The Provider panel on the left shows the same settings and keys that are shown when you create a new key. The Properties panel on the right allows you to set up some extra parameters, described below.

To add a new property, click the + Property button. This will bring up the Properties dialog, which contains the Parameter and Value fields. The following parameters are available:

• AllowApiKeyInQueryString: Use this parameter to allow the API key to be passed in the query string instead of in the HTTP header (see the Pass an API key section). The default value is False.

• AllowInsecureHttp: Use this parameter to allow the API key to be passed via an insecure HTTP request instead of a secure HTTPS request (see the Pass an API key section). The default value is False.

• HttpHeaderName: Use this parameter to change the name of the HTTP header that will pass the API key from the default X-API-Key.

• QueryStringParameterName: When you have also used the AllowApiKeyInQueryString option to pass the API key via one of the query string parameters, you can use this option to change the parameter's name from the default name apiKey (see the Pass an API key section).

Click Save and close the Properties dialog. The new parameter you've added will be listed in the Properties table.

Pass an API key

In most scenarios, Jitterbit recommends that the client pass the API key via a custom header in a secure HTTPS connection to limit the risk of exposure. The following example illustrates this:

GET /App Builder/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: ABCd0eFG1hiJKLMnOPQr2s

This is the default behavior, which App Builder adopts automatically. If you want or need to, you can use the HttpHeaderName parameter when configuring your API key to change the name of the HTTP header that will pass the API key from the default X-API-Key.

The following examples are some exceptions to this recommendation:

1. In some scenarios, HTTPS connections may be prematurely terminated. To work around this issue, you can force App Builder to accept API keys sent via HTTP connections by setting the AllowInsecureHttp parameter to True during API key configuration.

2. In cases where you don't have access to the HTTP request headers, it is also possible to send the API key via the query string parameters. To enable this option, set the AllowApiKeyInQueryString to True in the API key configurations. The example below illustrates how the API key is passed in this scenario:

   GET /App Builder/rest/v1/sales/customers?apiKey=ABCd0eFG1hiJKLMnOPQr2s HTTP/1.1
   HOST: example.com:443
   Accept: application/json
   

   Note that in the example above the key was sent under the name apiKey. You can change this by going to the API key configuration and adding the QueryStringParameterName parameter to choose a different name.