Dynamic API Key Retrieval

The OpenAPI specification used by Itential Platform now supports specification extensions via x-itential-parameters. Specifically for this feature, Integration Models with an apiKey security schema now support dynamic retrieval via the custom extension x-itential-dynamic-retrieval.

Integration Model With Dynamic Retrieval

An example integration model with the x-itential-dynamic retrieval extension is presented below.

Notice that x-itential-parameters are defined in the securitySchemes object, and the specific request the parameter is used in is defined by "x-itential-use-in": ["key"].

{
  ...
  "components": {
    "securitySchemes": {
      "apiKeySchemeName": {
        "type": "apiKey",
        "in": "header",
        "name": "my_auth",
        "x-itential-dynamic-retrieval": {
          "method": "POST",
          "url": "https://some.api.com/api/v2/key",
          "responsePointer": "/credentials/key"
        },
        "x-itential-parameters": [
          {
            "name": "password",
            "in": "query",
            "x-itential-use-in": [
              "key"
            ],
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}

In this example, the x-itential-dynamic-retrieval extension allows an integration instance to obtain an apiKey by issuing an HTTP call, performing a CRUD operation (specified by method) to a url, and then querying the response via JSON Pointer.

The expected reponse from calling POST to https://some.api.com/api/v2/key yields an object that looks like this:

{
  "credentials": {
    "key": "the api key value"
  }
}

The responsePointer will query /credentials/key and return the actual API key to use for authentication.

Wth this feature, the Integration instance will attempt to retrieve a new API key in the following scenarios:

• Before executing a task if the Integration has no stored API key value.
• After receiving an HTTP 401 response from an API call. In this scenario, the Integration will automatically retry the call one time (1x) after retrieving a new API key.

Related Reading

• Specification Extensions