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:
-
Click APIs.
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 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 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:
- 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.
-
Click 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.