> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/6/admin-essentials/integration-models/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Integration models > How to create, import, validate, and update integration models in Admin Essentials using OpenAPI specifications. An **integration model** defines an API for an integration. A model is loaded into Itential Platform using an OpenAPI specification. This page walks you through the steps for creating and using integration models for integrations in Admin Essentials, and covers current limitations. Available views, features, and interactions in the Platform interface can be limited based on user permissions. ## OpenAPI support Itential Platform supports OpenAPI 2.0 and 3.0 for creating integration models. When you import an OpenAPI 2.0 document, it's automatically converted to OpenAPI 3. All OpenAPI 3.0 documents must conform to the [OpenAPI v3.0 Specification](https://swagger.io/specification/). OpenAPI 3.0.4 is not supported. ## Importing an integration model #### Open Admin Essentials Log in to the Platform and navigate to **Admin Essentials**. #### Open the Import dialog Click the **Import** icon in the top toolbar to display the **Import** dialog. #### Select Integration Model Select **Integration Model** from the dropdown. The **Import** modal will display. #### Upload your specification file Upload a Swagger or OpenAPI file by drag-and-drop, or use the **Click to Browse** link to find and select the file you want to upload. In Itential Platform versions 2022.1 and 2023.1, when you create a new integration instance or install a new integration model in an HA environment, you must restart all otherItential Platform instances in the cluster to propagate the changes. Once the file is uploaded, the name of the integration model will pre-populate from the specification file, along with a description. You can change the description to provide specific information for your import and to better communicate what this integration is used for within your platform. ![](/_fern-img/4c5310ee4486b6272d5cb45cf95b7a7dc4e8978b01db6f7db3f54808f8f65de3.webp) ## Validating an imported integration model When you upload a Swagger 2.0 or OpenAPI 3.0 specification file, you can run validation on it using the **Validate** (✓) button. The OpenAPI specification file must be obtained from the targeted integration. For example, GitLab, Amazon, and Jenkins provide OpenAPI specifications that properly describe their APIs. Admin Essentials can ingest these files and enable integration with these technologies withinItential Platform. ![](/_fern-img/b30c2b078caec7d4d757c1dd1ded67bd58b13f1814fc68cb005843203b035a94.webp) Once you click the **Import** button, and upon successful import, the integration model will be added to the collection list in the left sidebar. When you select the integration model from the collection list, you will be redirected to the **Integration Model Details** page. ![](/_fern-img/3dfa5a83df30adee622af308a666fc268508077477f7005f95b1e51b66ac1301.webp) ### Known limitations The following are known limitations when creating an integration model, along with steps for editing after the model has been imported. #### Servers Currently a single server endpoint is supported for integrations. If the OpenAPI document has more than one server listed in its `servers` object, the first server will be selected for use. This endpoint can be updated in the service configuration after the integration is created. #### Example template for single server endpoint Any server URL using OpenAPI path template expressions will have the default value for variables applied. Below is an example of a configuration using multiple servers and URLs with path template expressions. ```json "servers": [ { "description": "The s3 multi-region endpoint", "url": "https://s3.{region}.amazonaws.com", "variables": { "region": { "default": "us-east-2", "description": "The AWS region", "enum": [ "us-east-1", "us-east-2", "us-west-1", "us-west-2" ] } } }, { "description": "The s3 multi-region endpoint", "url": "https://s3.{region}.amazonaws.com", "variables": { "region": { "default": "us-east-1", "description": "The AWS region", "enum": [ "us-east-1", "us-east-2", "us-west-1", "us-west-2" ] } } } ] ``` The resulting URL used in the service configuration will be: ```bash https://s3.us-east-2.amazonaws.com/ ``` This result is determined by taking the first server listed in the array and applying the default variable values to the template URL. This URL can be edited in the service configuration after the integration is created. ## Updating integration models It is currently not possible to edit an integration model after it has been imported into Itential Platform. Instead, the integration model must be deleted and replaced. #### Delete all associated integrations Delete all integrations associated with the model. #### Delete the integration model Delete the integration model itself. #### Import the updated model Import an updated version of the integration model. #### Recreate integrations Recreate all integrations associated with the model. #### Recreate workflow tasks Recreate any workflow tasks that reference prior integration versions, ensuring that each now references an updated version instead. This must be done on a per-workflow, task-by-task basis. ## Integration models with dynamic API key retrieval The OpenAPI specification used by Itential Platform supports specification extensions via `x-itential-parameters`. Specifically, integration models with an `apiKey` security schema now support dynamic retrieval via the custom extension `x-itential-dynamic-retrieval`. For additional context, see [OpenAPI Extensions](https://swagger.io/docs/specification/openapi-extensions/) and [Specification Extensions](https://swagger.io/specification/#specification-extensions). An example integration model with the `x-itential-dynamic-retrieval` extension is shown below. The `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"]`. ```json { ... "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 response from calling `POST` to `https://some.api.com/api/v2/key` yields: ```json { "credentials": { "key": "the api key value" } } ``` The `responsePointer` will query `/credentials/key` and return the actual API key to use for authentication. With this feature, the integration instance will attempt to retrieve a new API key in these 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 after retrieving a new API key. ## Related resources See [Integrations](/itential-platform/admin-essentials/integrations/overview). > How to create, import, validate, and update integration models in Admin Essentials using OpenAPI specifications.