Creating an API key security definition

When you create an API key security definition in an API, you specify the credentials that an application must provide to identify itself when calling the API operations.

To create an API key definition, complete the following steps:

1. In the navigation pane, click Develop, then select the APIs tab.
2. To create the security definition in an existing API, click the title of the API you want to work with. To create a new API to add the security definition to, see Creating an API definition.
3. Select Security Definitions and click Add.
4. Enter a name for the security definition and an optional description.
5. For Type, select API Key.
6. Specify whether the credentials are sent in the request header, or as query parameters, by selecting one of the following Located In options:

   Header

   The credentials are sent in the request header. This is the default setting.

   Query

   The credentials are sent as query parameters. This method is less secure because the client secret could be exposed in a log file.

   The selected option is enforced, and API calls fail if the credentials is included in the wrong location by the caller.

   Note: You must specify the same location for the client ID and client secret, either Header or Query.
7. Optional: Select the Key Type; the options are Client ID and Client Secret. Select the option that is applicable to the type of API key security definition you are creating.

   The field is mapped to the x-key-type property for the security definition in the OpenAPI source for the API, where the corresponding values are client_id and client_secret; use these values if you modify the OpenAPI source directly. If you do not select a value for the Key Type field, you instead use the Parameter name to specify the key type, as explained in step 8.

8. Specify the Parameter name.

   If your API is not enforced by the API Connect gateway, enter the parameter name required by your gateway.

   If your API is enforced by the IBM® API Connect gateway, the required value depends on the gateway type setting for the API, as follows:

   • DataPower API Gateway: if you did not select a value for the Key Type in step 7, then for a key of type client secret you must include the string secret, ignoring case, in the value you specify in the Parameter name field; if the value does not contain the string secret then the key is assumed to be of type client ID.

     If you did select a value for the Key Type then you can provide any value you like for the Parameter name field; the value is mapped to the name property for the security definition in the OpenAPI source for the API, allowing you set the name to any desired value while still retaining the required key type.

   • DataPower Gateway (v5 compatible): the value must be as specified in the following table, depending on where the client credentials are located, and the type of credentials. The field is automatically populated, according to value you select in the Located In field in step 6, as follows:

     • If there are no existing API key definitions of type client ID, the key type is assumed to be client ID.
     • If there is an existing API key definition of type client ID, the key type is assumed to be client secret.

     The value is mapped to the name property for the security definition directly in the OpenAPI source. If the pre-populated value is not what you require, modify the value of the name property directly in the OpenAPI source on the Source tab.

     Table 1. Client ID and Client secret parameter name values for the DataPower® Gateway (v5 compatible)

     Location of credentials	Type of credentials	Parameter name
     Header	Client ID	X-IBM-Client-Id
     Header	Client secret	X-IBM-Client-Secret
     Query	Client ID	client_id
     Query	Client secret	client_secret

   When you first create an API, a default API key security definition, of type client ID, is provided.

   For information about including API key parameters in an API call, see Calling an API.

   Note:

   • You cannot apply more than two API key security definitions to an API.
   • If you apply an API key security definition for client secret, you must also apply an API key security definition for client ID.
   • If you require the application developer to supply both client ID and client secret, you must apply two separate API key security definitions.
   • You can have at most one API key definition of type client ID, regardless of whether the client ID is sent in the request header or as a query parameter.
   • You can have at most one API key definition of type client secret, regardless of whether the client secret is sent in the request header or as a query parameter.
   • The client ID and client secret headers that are specified in the request when the API is called are not added automatically to the message context. If you need these headers in the message context for subsequent processing, include a set-variable policy in your API assembly that adds the headers to the message content, taking the values specified in the request; you can do this in either of the following ways:
     • In the Assemble tab, add a Set Variable policy to your API assembly that defines the appropriate actions; for example:

       Table 2.

       Action	Set	Type	Value
       Set	message.headers.X-IBM-Client-Id	string	$(request.headers.X-IBM-Client-Id)
       Set	message.headers.X-IBM-Client-Secret	string	$(request.headers.X-IBM-Client-Secret)

       For more information on configuring a Set Variable policy, see Set Variable.
     • In the Source tab, add a set-variable policy directly to the assembly section in your OpenAPI source; for example:

       assembly:
         execute:
           - set-variable:
               version: 2.0.0
               title: set-variable
               actions:
                 - set: message.headers.X-IBM-Client-Id
                   value: $(request.headers.X-IBM-Client-Id)
                   type: string
                 - set: message.headers.X-IBM-Client-Secret
                   value: $(request.headers.X-IBM-Client-Secret)
                   type: string

       For more information on defining a set-variable policy in your OpenAPI source, see set-variable.
     You should position the set-variable before any policy that needs to access the API key headers; for example, an invoke policy that calls a back-end service that is required to identify the application that made the initial request.
9. Click Save to save your changes.