Defining API key security schemes
An API key security scheme is used to specify the credentials that an application must provide to identify itself when calling the API operations.
About this task
You can complete this task either by using the API Designer UI application, or by using the browser based API Manager UI.
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 scheme 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 schemes, one for each type of credentials.
To make use of an API key security scheme, you must reference it from elsewhere in your API definition. For more information, see Enforcing security requirements on an API and Enforcing security requirements on an operation.
At any time, you can switch directly to the underlying OpenAPI YAML source that corresponds to the design form in the user interface by clicking the Source icon . To return to the design form, click the Form icon .
- Open the required API for editing, as described in Editing an OpenAPI 2.0 API definition.
- If there are already one or more security schemes defined, expand Security Schemes.
- To create an API key security scheme, click the add icon alongside Security Schemes, then select apiKey for the Security Definition Type. To edit an API key existing security scheme, click the security scheme name in the navigation pane.
- Enter an identifying name of your choice in the Security Scheme Name field.
Specify the parameter name in the Name field.
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: For a key
of type client secret, you must include the string
secret, ignoring case, in the value you specify in the Name field; if the value does not contain the string
secretthen the key is assumed to be of type client ID.
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.
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-variablepolicy 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:
For more information on configuring a Set Variable policy, see Set Variable.
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)
- In the Source tab, add a
set-variablepolicy directly to the assembly section in your OpenAPI source; for example:
For more information on defining a
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
set-variablepolicy in your OpenAPI source, see set-variable.
set-variablebefore 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.
- In the Assemble tab, add a Set Variable policy to your API assembly that defines the appropriate actions; for example:
- DataPower® API Gateway: For a key of type client secret, you must include the string
- Select the Key Type: client_id or
client_secret. Important: The client_id is not confidential and functions as a "SecurityScheme" only in the meaning of the OpenAPI specification.
If you use only the client_id (without the client_secret) as your API Key, be aware that the client_id is not considered a confidential value in the API Manager UI; for example, it might be displayed to other authenticated members of the provider organization. The client_id is treated as a public identifier for apps and cannot be kept private.
If authentication of the identity of the app calling an API is needed, then the API Key should use both a client_id to identify the app, plus a client_secret to authenticate it. The client_secret is designed to be known only to the app and the authorization server, and it should be protected. IBM API Connect protects the client_secret: it is only available when first generated, it can be stored as a one-way hash to prevent retrieval or leaks, and it can be changed and reset without changing the corresponding client_id. When an API Key is not marked as a client_secret, it will not be protected in the API Manager UI.
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 are 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.
- If you migrated from API Connect V5, API key security definitions that contain multiple Client ID references, behave differently in Version 10 than in Version 5. For information about the differences, see Client ID behavior in API key security definitions.
- Optionally, provide a Description for the security scheme. You can use CommonMark syntax for rich text representation.
- If you are creating a new API key security scheme, click
Create. The security scheme details are displayed for further editing.
- Click Save when done.