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.

About this task

You can require that, when calling an API operation, an application must provide either a client ID, or a client ID and client secret; you create an API key security definition to specify a credentials requirement. If you require that an application must provide both a client ID and client secret, you must create two API key security definitions, one for each type of credentials.

Note: The API Manager UI also includes the ability to create and edit security definitions. However, the preferred method for these tasks is by using the API Designer UI, as described here. Any steps that are specific to a particular UI are marked with an icon.

Procedure

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

  1. Click APIs.
    The APIs tab opens.
  2. If you have not previously pinned the UI navigation pane then click the Navigate to icon The Navigate to icon.
    The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon The Pin menu icon..
  3. Click Drafts in the UI navigation pane, and then click APIs.
    The APIs tab opens.
  4. To create the security definition in an existing API, click the API you want to work with. To create a new API to add the security definition to, see Creating API definitions.
  5. Navigate to the Security Definitions section.
  6. In the Security Definitions section, click the Add Security Definition icon The add security definition icon..
  7. Select API Key.
  8. Enter a name for the security definition, to replace the default name, and, optionally, a description.
  9. Enter the Parameter name.
    If your API is enforced by the IBM® API Connect for IBM Cloud gateway, enter one of the following values depending on where the client credentials are to be located, and the type of credentials that are required:
    Table 1. Client ID and Client secret parameter name values
    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

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

    When you change the location of an API key security definition's credentials, the parameter name changes appropriately.

    When you first create an API, default API key security definitions are 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.
  10. 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.
  11. Click the Save icon The Save icon. to save your changes.

What to do next

Apply your security definition to the API, or to one or more API operations. For more information, see Applying security definitions to an API and Applying security definitions to an API operation.