Defining API key security scheme components

An API key security component is used to specify the credentials that an application must provide to identify itself when calling the API operations.

1. Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
2. Expand Components then, if there are already one or more security scheme components defined, expand Security Schemes.
3. To create an API key security scheme component, click the add icon alongside Security Schemes. To edit an API key existing security scheme component, click the component name in the navigation pane.
4. If you are creating a new API key security scheme component, you can either create it from scratch or you can reference another API key security scheme component.
   To create an API key security scheme component from scratch, provide the following information on the Definition tab:

   • Security Scheme Name: A key that enables this API key security scheme component to be referenced from elsewhere in the API definition; the reference has the following format:

     #/components/securitySchemes/Security_Scheme_Name

   • Security Scheme Type: Select apiKey.
   • Name: The name of the header, query or cookie parameter to be used. 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 secret then the key is assumed to be of type client ID.
     Note: 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 1.

       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.
   • Key Type: Select 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.

   • Located In: Select one of the following options, to specify how the credentials are sent:
     • header: The credentials are sent in the request header.
     • query: The credentials are sent as query parameters. This method is less secure because the client secret could be exposed in a log file.
     Note: 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.
   • Description: An optional description of the API key security scheme. You can use CommonMark syntax for rich text representation.

5. To reference another API key security scheme component, provide the following information on the Reference tab:
   • Security Scheme Name: A key that enables this API key security scheme component to be referenced from elsewhere in the API definition; the reference has the following format:

     #/components/securitySchemes/Security_Scheme_Name

   • Reference from: Select a reference to another API key security scheme component.
6. If you are creating a new API key security scheme component, click Create.
   The security scheme component details are displayed for further editing.
7. Click Save when done.