> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/admin-essentials/integrations/auth/openapi-extensions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# OpenAPI extensions for auth

> How to use x-itential-parameters OpenAPI extensions for custom OAuth2 and OIDC authorization in Platform 6 integrations.

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](https://swagger.io/docs/specification/openapi-extensions/) and [Specification Extensions](https://swagger.io/specification/#specification-extensions).

### Example

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

```json
{
    "openapi": "3.0.0",
    "info": {
        "title": "ServiceNow Product Order API",
        "description": "API for managing product orders in ServiceNow",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https://example.service-now.com"
        }
    ],
    "paths": {},
    "security": [
        {
            "oauth2": []
        }
    ],
    "components": {
        "schemas": {
            "ProductOrder": {
                "type": "object",
                "properties": {
                    "orderId": {
                        "type": "string",
                        "description": "ID of the product order"
                    }
                }
            }
        },
        "securitySchemes": {
            "oauth2": {
                "type": "oauth2",
                "flows": {
                    "clientCredentials": {
                        "tokenUrl": "",
                        "refreshUrl": "",
                        "scopes": {}
                    }
                },
                "x-itential-parameters": [
                    {
                        "name": "client_assertion",
                        "in": "header",
                        "description": "assertion header",
                        "x-itential-use-in": [
                            "refresh",
                            "token"
                        ],
                        "x-itential-variable": "clientAssertion"
                    },
                    {
                        "name": "other_test",
                        "in": "body",
                        "description": "test body",
                        "x-itential-use-in": [
                            "refresh",
                            "token"
                        ],
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "nice_one",
                        "in": "query",
                        "description": "test body",
                        "x-itential-use-in": [
                            "refresh"
                        ],
                        "x-itential-variable": "niceOne",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "asdf_cool",
                        "in": "header",
                        "description": "test body",
                        "x-itential-use-in": [
                            "refresh",
                            "token"
                        ]
                    }
                ]
            }
        }
    }
}
```

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.

![](/_fern-img/0afbe2f44b63da8e5b3924f7f300017b63f34ba533b83fc1834e0bdfeede580c.webp)

## Itential specification extensions

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

| Extension               | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-itential-variable`   | string              | Use in [Parameter Objects](https://swagger.io/specification/#parameter-object) 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-parameters` | parameter-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](https://swagger.io/specification/#components-object), [Path Item Object](https://swagger.io/specification/#path-item-object), and [Operation Object](https://swagger.io/specification/#operation-object). You can also define parameters in the [Security Scheme Object](https://swagger.io/specification/#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-in`     | string\[]           | When you define additional parameters during OAuth 2.0 grant flows, the model applies to multiple requests. Valid values are: `"authorization"`, `"token"`, `"refresh"`, `"openIdConnect"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

> How to use x-itential-parameters OpenAPI extensions for custom OAuth2 and OIDC authorization in Platform 6 integrations.