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.
To create an API key definition, complete the following steps:
The APIs tab opens.
If you have not previously pinned the UI navigation pane then
click the Navigate to icon .
The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
Click Drafts in the UI navigation pane, and then click APIs.
The APIs tab opens.
- 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.
- Navigate to the Security Definitions section.
- In the Security Definitions section, click the Add Security Definition icon .
- Select API Key.
- Enter a name for the security definition, to replace the default name, and, optionally, a description.
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.
Specify whether the credentials are sent in the request header, or as query parameters, by selecting one of the following Located In options:
- The credentials are sent in the request header. This is the default setting.
- 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.
- Click the Save icon to save your changes.