> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting entities to Apiiro

<Info>
  Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
</Info>

This article explains how to connect Cortex entities to Apiiro. For configuration instructions, see [Configuring the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro). For what you can do once entities are connected, see [Using the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro/using-the-integration-for-apiiro).

## Connecting an entity to Apiiro

Before Cortex can show Apiiro risks on an entity, the entity needs to be connected to an application or repository in Apiiro. Cortex connects entities to Apiiro repositories automatically when their repository paths match. To connect an entity to an application, or to a repository whose path doesn't match, map it in the entity's YAML.

This page explains both methods and how to confirm that an entity is connected.

## Importing entities from Apiiro

The Apiiro integration doesn't import entities into Cortex. It adds security risk data to entities that already exist in your catalog. To add entities to Cortex, see [Adding entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities).

## Connecting entities automatically

If an entity has a git repository and no `x-cortex-apiiro` block, Cortex connects it to any Apiiro repository with the same path.

Cortex compares the repository path from the entity's `x-cortex-git` block (for example, `my-org/my-service`) to the repository paths in Apiiro. Keep these rules in mind:

* **Matches are exact.** Matching is case-sensitive, and Cortex doesn't normalize spaces or punctuation. `My-Org/My-Service` doesn't match `my-org/my-service`.
* **Only paths are compared.** Cortex doesn't match on repository URLs, repository IDs, entity names, or Cortex tags.
* **Every match is kept.** If more than one Apiiro repository has the same path, Cortex connects the entity to all of them.
* **Applications aren't matched automatically.** To connect an entity to an Apiiro application, [map it manually](#connecting-entities-manually).

**Cortex refreshes its list of Apiiro repositories every night at 10 p.m. UTC**. A repository you add to Apiiro won't match any entities until after the next refresh. Cortex matches entities to repositories when it loads their Apiiro data, so you don't need to take any action after you configure the integration.

<Note>
  Automatic matching requires a git repository on the entity. Entities without an `x-cortex-git` block only connect to Apiiro through manual mapping.
</Note>

## Connecting entities manually

Add an `x-cortex-apiiro` block to an entity's YAML to connect it to specific Apiiro repositories or applications. Use manual mapping when:

* You want to connect an entity to an Apiiro application.
* The entity's repository path doesn't exactly match the path in Apiiro.
* The entity doesn't have a git repository in Cortex.

<Warning>
  A manual mapping replaces automatic matching for that entity. If you add an `x-cortex-apiiro` block that lists only applications, Cortex stops matching the entity's git repository. To keep the repository connected, list it under `repositories` as well.
</Warning>

### Mapping an entity in its YAML

1. In Apiiro, find each repository or application you want to connect to the entity. For a repository, you can use either its ID or its path (e.g. `my-org/my-service`). For an application, you need its ID.
2. In Cortex, navigate to the entity's YAML:
   1. From the main sidebar, expand **Catalogs**, then select **All entities**.
   2. Do one of the following:
      * Select the **All** tab to search and filter across all of your organization’s entities.
      * Select the **Mine** tab to search and filter only the entities you own.
      * Note that Cortex saves your selection and restores it the next time you open this page.
   3. Select your entity.
   4. From the [entity's left sidebar](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-details-sidebar), select **Entity YAML**.
   5. In the upper-right corner, click **Configure entity**.
3. Add an `x-cortex-apiiro` block. You can list repositories, applications, or both. Set each entry's `alias` to the alias of your Apiiro configuration in Cortex.
   ```yaml theme={null}
   x-cortex-apiiro:
     repositories:
       - alias: alias-one
         repositoryId: repository-one
       - alias: alias-one
         repositoryPath: my-org/my-service
     applications:
       - alias: alias-one
         applicationId: application-one
   ```
4. Click **Save changes**.

### Field reference

| Field | Description | Required |
| - | - | - |
| `repositories` | A list of Apiiro repositories to connect to the entity. | No |
| `repositories[].alias` | The alias of the Apiiro configuration in Cortex. You set this when you add a configuration on the Apiiro settings page. | Yes |
| `repositories[].repositoryId` | The ID of the repository in Apiiro. | Use either `repositoryId` or `repositoryPath`, not both |
| `repositories[].repositoryPath` | The path of the repository in Apiiro, for example `my-org/my-service`. | Use either `repositoryId` or `repositoryPath`, not both |
| `applications` | A list of Apiiro applications to connect to the entity. | No |
| `applications[].alias` | The alias of the Apiiro configuration in Cortex. | Yes |
| `applications[].applicationId` | The ID of the application in Apiiro. | Yes |

You can include `repositories`, `applications`, or both. If an entity has neither, Cortex uses [automatic matching](#connecting-entities-automatically).

<Warning>
  Every entry needs an `alias`, and every repository entry needs exactly one of `repositoryId` or `repositoryPath`. If any entry is missing a required field, Cortex ignores the entire `x-cortex-apiiro` block without showing an error.
</Warning>

### How repository and application mappings differ

Both types of mapping show risks in the same places: the **Code & security** block on the entity's overview page, and `apiiro.risks()` in CQL. The difference is which risks Cortex pulls in:

* **Repository mapping** - Cortex shows only the risks in that repository.
* **Application mapping** - Cortex shows every risk Apiiro associates with that application, which can span multiple repositories.

If an entity has both, Cortex combines the results and removes duplicates, so each risk appears once.

<Note>
  The **Code & security** block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn't appear.
</Note>

### Using multiple configurations

If you have more than one Apiiro configuration in Cortex (for example, one for each Apiiro instance), one entity can connect to repositories and applications under different aliases. Cortex pulls risks from each configuration, then combines the results and removes duplicates.

```yaml theme={null}
x-cortex-apiiro:
  repositories:
    - alias: alias-one
      repositoryId: repository-one
  applications:
    - alias: alias-two
      applicationId: application-two
```

## Verifying the connection

After an entity is connected, check that its Apiiro data appears in Cortex:

* **On the entity's details page** - Risks appear in the **Code & security** block on the overview, grouped by severity. For the full list, go to **Security > Apiiro** in the entity's sidebar.
  <Note>
    The **Code & security** block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn't appear.
  </Note>
* **With CQL** - Run `apiiro != null` in the [Query builder - US](https://app.getcortexapp.com/admin/queries) / [Query builder - EU](https://app.eu.cortex.io/admin/queries) to find entities that are connected to Apiiro. Entities that don't appear in the results aren't connected.


## Related topics

- [Apiiro](/ingesting-data-into-cortex/integrations/apiiro.md)
- [Using the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro/using-the-integration-for-apiiro.md)
- [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes.md)