Call an API secured with an API key

An API key is a code passed by an application that is calling an API. It is used to establish the identity of the calling application.

The API key can act as both a unique identifier and a secret for authentication, and will typically have a set of access rights on the API associated with it.

To call a RESTful API protected by an API key, the CICS, IMS, or z/OS application, must include the API key as an authentication or authorization credential in the request.

Figure 1. Calling an API secured with an API key.
Using an API key to call a RESTful API.

Figure 1 shows the API key credentials provided by the z/OS application, being sent by the communication stub to the IBM® z/OS® Connect server and then propagated to the RESTful API either in a query string or as a request header.

The API key credentials can be a Client ID, or a Client ID and Client secret. Table 1 shows the different API key options and example parameter names.

Table 1. Client ID and Client secret parameter name examples
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

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