AppsAdmin EssentialsIntegrations and modelsAuthentication

OpenAPI extensions for auth

Itential Platform supports custom parameters for integrations through the x-itential-parameters OpenAPI specification extension. This feature enables custom parameters for OAuth2 and OpenID Connect Discovery authorization requests, including token and refresh requests.

For related reading, see OpenAPI Extensions and Specification Extensions.

Example

The following example shows an imported integration model with x-itential-parameters defined in the securitySchemes object:

1{
2    "openapi": "3.0.0",
3    "info": {
4        "title": "ServiceNow Product Order API",
5        "description": "API for managing product orders in ServiceNow",
6        "version": "1.0.0"
7    },
8    "servers": [
9        {
10            "url": "https://example.service-now.com"
11        }
12    ],
13    "paths": {},
14    "security": [
15        {
16            "oauth2": []
17        }
18    ],
19    "components": {
20        "schemas": {
21            "ProductOrder": {
22                "type": "object",
23                "properties": {
24                    "orderId": {
25                        "type": "string",
26                        "description": "ID of the product order"
27                    }
28                }
29            }
30        },
31        "securitySchemes": {
32            "oauth2": {
33                "type": "oauth2",
34                "flows": {
35                    "clientCredentials": {
36                        "tokenUrl": "",
37                        "refreshUrl": "",
38                        "scopes": {}
39                    }
40                },
41                "x-itential-parameters": [
42                    {
43                        "name": "client_assertion",
44                        "in": "header",
45                        "description": "assertion header",
46                        "x-itential-use-in": [
47                            "refresh",
48                            "token"
49                        ],
50                        "x-itential-variable": "clientAssertion"
51                    },
52                    {
53                        "name": "other_test",
54                        "in": "body",
55                        "description": "test body",
56                        "x-itential-use-in": [
57                            "refresh",
58                            "token"
59                        ],
60                        "schema": {
61                            "type": "string"
62                        }
63                    },
64                    {
65                        "name": "nice_one",
66                        "in": "query",
67                        "description": "test body",
68                        "x-itential-use-in": [
69                            "refresh"
70                        ],
71                        "x-itential-variable": "niceOne",
72                        "schema": {
73                            "type": "number"
74                        }
75                    },
76                    {
77                        "name": "asdf_cool",
78                        "in": "header",
79                        "description": "test body",
80                        "x-itential-use-in": [
81                            "refresh",
82                            "token"
83                        ]
84                    }
85                ]
86            }
87        }
88    }
89}

In this example, the oauth2 request uses four custom parameters:

  • The x-itential-variable properties are not specific to the security scheme.
  • The x-itential-use-in property defines which requests use the parameter.
  • The client_assertion header maps to the clientAssertion variable defined in the integration and applies to both token and refresh requests.
  • When x-itential-variable is not defined on a parameter, the request uses the value set under “parameters” in the integration, specific to the security scheme.
Integration custom URI parameters

Itential specification extensions

This section explains Itential’s custom OpenAPI specification extensions and their impact on API interactions.

ExtensionTypeDescription
x-itential-variablestringUse in Parameter Objects to define variables that are captured in the service configuration properties per instance of an integration. The value of this field is the variable name, which also serves as a unique identifier. Using the same variable name in multiple places generates only one variable, and its runtime value applies to all instances.
x-itential-parametersparameter-object[]The OpenAPI specification defines a model for parameters, which are parts of an API request such as headers, query parameters, path parameters, and cookies. You can define these parameters in the Components Object, Path Item Object, and Operation Object. You can also define parameters in the Security Scheme Object, where additional parameters may be needed for authorization. The Parameter Objects in the array are nearly identical to the OpenAPI Specification definition of a Parameter Object. The only difference is that parameters in a Security Scheme Object can use the additional value of "body" for the "in" field when the security request has an x-www-form-urlencoded request body (for example, OAuth 2.0 grant flows). Each parameter must provide either a schema or content property.
x-itential-use-instring[]When you define additional parameters during OAuth 2.0 grant flows, the model applies to multiple requests. Valid values are: "authorization", "token", "refresh", "openIdConnect".