How to configure an API key

To call a REST API protected by an API key, your CICS, IMS or 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 IBM z/OS Connect server to the RESTful API in either a query string or as a request header.

This task is applicable when IBM 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 build toolkit. You must also specify values for these API key parameters in your CICS, IMS or z/OS application.

API key definitions

API key definitions can be provided using either a Swagger file or aIBM z/OS Connect build toolkit properties.

Swagger files

You can find API key definitions in the security definitions section of a Swagger file. In the following example, a security schema apiKeyHeader specifies an API key X-IBM-Client-ID. When calling this REST 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.


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

API key definitions in a Swagger file can be used to control access for all operations of the API or to a subset of the operations of the API.

Build toolkit properties

If the API key definition for an API is not specified in the Swagger file, you must specify the API key definition with the following build toolkit properties:

apiKeyParmNameInHeader: The name of an API key that is sent as a request header, for example, header-IBM-Client-Secret. 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, query-IBM-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 values set for API key.

API key definitions specified using build toolkit properties can be used to control access for all operations of the API, but cannot be used to control access to a subset of the operations of the API.

For more information about build toolkit properties for API keys, see The build toolkit properties file.

Important:

If both a Swagger file and IBM z/OS Connect build toolkit properties are used to define API key names, only the API key names that are defined using the build toolkit properties are used to generate the names of the API key parameters that are in the request data structures.
The Swagger file 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 build toolkit 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 build toolkit to generate API key parameters in the request data structure.
For example, if you set apiKeyParmNameInHeader to X-IBM-Client-Secret and apiKeyMaxLength to 255 in the build toolkit properties file, the following lines will be generated in the request data structure:
```
06 ReqHeaders.   
09 X-IBM-Client-Secret-Length     PIC S9999 COMP-5 SYNC.   
09 X-IBM-Client-Secret            PIC X(255).
```
X-IBM-Client-Secret-Length is a parameter that is automatically generated by the build toolkit based on the API key parameter X-IBM-Client-Secret. X-IBM-Client-Secret-Length specifies the length of the value of the X-IBM-Client-Secret parameter.
Specify the API key values, X-IBM-Client-Secret and X-IBM-Client-Secret-Length in your z/OS application program.