How to configure an API key

To call an API protected by an API key, your z/OS® application must include the API key as an authentication or authorization credential in the request. The API key credentials are propagated by the z/OS Connect Server to the API in either a query string, request header, or cookie.

zosConnect-3.0 Applies to zosConnect-3.0.

This task is applicable when z/OS Connect is used as an API requester.

To enable API key authentication, you must have API key definitions to generate API key parameters in request data structures by using the Gradle plug-in. You must also specify values for these API key parameters in your z/OS application.

API key definitions

API key definitions can be provided by using either an OpenAPI document or the z/OS Connect Gradle plug-in properties.

OpenAPI documents

You can find API key definitions in the security definitions section of a OpenAPI document. In the following example, a security scheme apiKeyHeader specifies an API key X-IBM-Client-ID. When calling this API, the request header X-IBM-Client-ID: <keyValue> must be provided for authentication or authorization, where <keyValue> is the value of the API key X-IBM-Client-ID.

Example API key header definition for an OpenAPI JSON document

"securitySchemes": { 
    "apiKeyHeader": { 
        "type": "apiKey",
        "name": "X-IBM-Client-ID", 
        "in": "header" 
    }
}

Example API key header definition for an OpenAPI YAML document

securitySchemes:
    apiKeyHeader:
        type: apiKey 
        name: X-IBM-Client-ID 
        in: header

Example API key header definition for an OpenAPI YAML document

securitySchemes:
    apiKeyHeader:
        type: apiKey 
        name: X-IBM-Client-ID 
        in: header

API key definitions in an OpenAPI document can be used to control access for all operations of the API or to a subset of the operations of the API by adding a security requirement object to the corresponding section of the OpenAPI document.

Example security section to reference an API key for an OpenAPI JSON document

"security": [
  "apiKeyHeader": [ ]
]

Example security section to reference an API key for an OpenAPI YAML document

security:
- apiKeyHeader: []

Gradle build properties

If the API key definition for an API is not specified in the OpenAPI document, you must specify the API key definition with one of the following Gradle plug-in properties in the options.yaml file:

apiKeyParmNameInHeader - The name of an API key that is sent as a request header, for example, X-IBM-Client-ID. The value of this property can be a comma-separated list to include client ID and client secret.
apiKeyParmNameInQuery - The name of an API key that is sent in a query string, for example, client_id. The value of this property can be a comma-separated list to include client ID and client secret.
apiKeyParmNameInCookie - The name of an API key that is sent in a cookie, for example, client_secret. The value of this property can be a comma-separated list to include client ID and client secret.
apiKeyMaxLength- The maximum length of the value set for API key.

API key definitions that are specified by using Gradle plug-in properties can be used to control access for all operations of the API. However, Gradle plug-in properties cannot be used to control access to a subset of the operations of the API.

For more information about Gradle plug-in properties for API keys, see The API requester Gradle plug-in properties and options.

Important:

Security requirements can be specified for a specific operation, globally for all operations in the API, and also for apiKey security requirements with the API requester Gradle plug-in options.

The order of precedence is operation-defined security requirements overrides globally defined security requirements that overrides any Gradle plug-in apiKeyParmNameInHeader, apiKeyParmNameInQuery, or apiKeyParmNameInCookie parameters.
The OpenAPI document does not support specifying the maximum length of the key value of an API key. If you want to specify the maximum length of the key value of an API key, set the Gradle plug-in property apiKeyMaxLength. The value of apiKeyMaxLength is applied to all the API keys for an API.

How to enable API key authentication

To enable the z/OS application to send the API key credentials with the API request, you must complete the following steps:

Run the Gradle build to generate API key parameters in the request data structure.
For example, if you set apiKeyParmNameInHeader to X-IBM-Client-ID and apiKeyMaxLength to 255 in the z/OS Connect Gradle plug-in properties, the following lines are generated in the request data structure:
```
06 ReqHeaders.   
  09 X-IBM-Client-ID-Length     PIC S9999 COMP-5 SYNC.   
  09 X-IBM-Client-ID            PIC X(255).
```
X-IBM-Client-ID and X-IBM-Client-ID-Length are parameters that are automatically generated by the Gradle plug-in based on the API key parameter X-IBM-Client-ID. X-IBM-Client-ID-Length specifies the length of the value of the X-IBM-Client-ID parameter.
Specify the API key values X-IBM-Client-ID, and X-IBM-Client-ID-Length in your z/OS application.
For example, in a COBOL application.
1. Define the value for the API key in the WORKING-STORAGE SECTION:
```
       01 CLIENT-ID PIC X(10) VALUE 'myClientID'.
```
2. Then in the PROCEDURE DIVISION before calling the Host API BAQEXEC verb, set the API key value in the generated request copybook fields.
```
           MOVE CLIENT-ID TO X-IBM-Client-Id OF BAQBASE-RBK00Q01.
           MOVE LENGTH OF CLIENT-ID TO X-IBM-Client-Id-Length 
               OF BAQBASE-RBK00Q01.
```