Cortex

System Management

Overview

The Cortex connector integrates with Cortex — an internal developer portal and service catalog — through its REST API. It synchronizes the service/resource catalog, the teams that own those entities, and the people who belong to those teams. This data lets Brinqa understand application/service ownership and map assets and findings to the teams and individuals responsible for them.

The connector syncs three models:

• Catalog — entries in the Cortex service/software catalog (services, domains, resources, etc.), including their git source, hierarchy, owners, members, and metadata.
• Team — Cortex teams, their metadata, members, and the catalog entity they map to.
• Person — individual members derived from team membership, including their role within the team.

Data retrieved from Cortex

Connector Object	Required	Maps to Data Model
Catalog	Yes	(none — SDM only)
Team	Yes	Team
Person	Yes	Person

Model relationships

note

For detailed steps on how to view the data retrieved from Cortex in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select Cortex from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Server URL	Yes	https://api.getcortexapp.com/	Cortex server URL
Api token	Yes	(none)	Cortex api token

Authentication

Cortex authenticates using a Bearer API token. The token is configured on the connector and sent on every request in the Authorization header. There is no token-exchange/login step — the configured token is used directly.

The connector validates connectivity by calling the teams endpoint.

Endpoint

Method	URL
GET	{url}/api/v1/teams

Request Headers

Header	Value
Authorization	Bearer {apiToken}
Accept	application/json

Request Body

None. The token is supplied via the Authorization header.

Sample Response

A successful call returns the teams payload (HTTP 200):

{
  "teams": [
    {
      "teamTag": "machine-learning-and-ai",
      "catalogEntityTag": "machine-learning-and-ai",
      "metadata": {
        "name": "Machine Learning and AI",
        "description": null,
        "summary": null
      },
      "links": [],
      "slackChannels": [],
      "isArchived": false,
      "cortexTeam": {
        "members": [
          {
            "email": "cristina.buenahora@cortex.io",
            "name": "Cristina Buenahora",
            "description": "",
            "role": null
          }
        ]
      },
      "type": "CORTEX"
    }
  ]
}

Response Fields

Field	Description
teams[]	Array of team objects. Presence of this array confirms a valid token and connectivity.

Token Usage

The same Bearer token is attached to every subsequent catalog, team, and person request via the Authorization: Bearer {apiToken} header. If the credential is missing or invalid, the API returns an error which the connector surfaces as a connection failure.

Sync Behavior

The connector supports incremental (delta) syncs. It maintains a sync token between runs and applies it as an incremental timestamp filter, so each run re-processes only the records that changed after the previous sync. The initial run retrieves the complete data set; later runs are incremental. The specific timestamp field applied to each object is documented under that object's Sync Duration Parameter.

How to obtain Cortex credentials

Generate a Cortex API token

For the Cortex connector to use the Cortex API, you must provide an access token. You can use either a personal access token or an API token to retrieve data from the Cortex API.

To generate an API token, follow these steps:

1. Log in to your organization's Cortex portal as an administrator.

   Only administrators can access the API Keys page and create API keys.

2. Click the User Profile icon in the top-right corner and then click My Preferences from the dropdown.

3. Click API Keys and then click Create API key.

   The Create API Key dialog displays. Complete the following fields:

   • API Key Role: Click the dropdown and select the role to determine the level of access.

     For the Cortex connector, select Viewer from the dropdown. The Viewer role is a read-only role and is considered to be the minimum role needed to read and retrieve data.

   • Description: (Optional) Provide a description for the token.

4. Click Create API Key.

   Your new API token appears. You cannot view the token after this. Copy the token and save it to a secure location.

Note: If you do not have permissions to create an API token, contact your Cortex administrator. For additional information, see Cortex documentation.

To generate a new personal access token, follow these steps:

1. Log in to your organization's Cortex portal.

2. Click the User Profile icon in the top-right corner and then click My Preferences from the dropdown.

3. Click Personal access tokens and then click Create new token.

   The Create personal access token dialog displays. Complete the following fields:

   • Name: Provide a name for the token.

   • Description: (Optional) Provide a description for the token.

   • Expiration date: Provide an expiry date for the token.

     

4. Click Create access token.

   Your new personal access token appears. You can not view the token after this. Copy the token and save it to a secure location.

   

Note: Personal access tokens inherit the permissions of the user creating the token. At the very least, a User or Viewer role is required to retrieve data from the Cortex API. If permissions aren't sufficient to make API calls, you will receive a 403 error. For additional information, see Cortex documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Catalog

Source Field Name	SDM Attribute
description	DESCRIPTION
git.alias	GIT_ALIAS
git.basepath	GIT_BASEPATH
git.provider	GIT_PROVIDER
git.repository	GIT_REPOSITORY
git.repositoryUrl	GIT_REPOSITORY_URL
groups	GROUPS
hierarchy.children[].tag	CHILDREN
hierarchy.parents[].tag	PARENTS
isArchived	IS_ARCHIVED
lastUpdated	SOURCE_LAST_MODIFIED
links[].url	REFERENCES
members[].email	MEMBERS
metadata[].key / metadata[].value	METADATA
name	NAME
owners.individuals[].email	OWNER_INDIVIDUALS
owners.teams[].tag	OWNER_TEAMS
slackChannels[].channel	SLACK_CHANNELS
tag	UID
type	CATALOG_TYPE

Team

Source Field Name	SDM Attribute
catalogEntityTag	CATALOG
cortexTeam.members[].email	MEMBERS
isArchived	IS_ARCHIVED
links[].url	REFERENCES
metadata.description	METADATA_DESCRIPTION
metadata.name	METADATA_NAME
metadata.summary	METADATA_SUMMARY
slackChannels[].channel	SLACK_CHANNELS
teamTag	UID
teamTag	NAME
type	TEAM_TYPE

Person

Source Field Name	SDM Attribute
constant	CATEGORIES
cortexTeam.members[].description	DESCRIPTION
cortexTeam.members[].email	UID
cortexTeam.members[].email	EMAIL
cortexTeam.members[].name	NAME
cortexTeam.members[].role.name	ROLE_NAME
cortexTeam.members[].role.source	ROLE_SOURCE
cortexTeam.members[].role.tag	ROLE
cortexTeam.members[].role.type	ROLE_TYPE

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Catalog

Operation options

Option	Type	Default	Description
owners	Filters catalog entities by owner (passed through as the owners query parameter).	—
types	Filters catalog entities by type (passed through as the types query parameter).	—

Delta sync

Supported.

API

• Type: REST endpoint · Endpoint: GET /api/v1/catalog
• Default filters: includeOwners=true, includeMetadata=true, includeLinks=true (plus optional owners and types from operation options)

Team

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: REST endpoint · Endpoint: GET /api/v1/teams

Person

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: REST endpoint · Endpoint: GET /api/v1/teams

Changelog

Changelog

The Cortex connector has undergone the following changes:

Version	Description	Migration Steps
3.0.1	Improvements - Catalog entities now include their associated links (such as documentation, dashboards, and runbook URLs) when synchronized, giving a more complete view of each catalog entry. Dependency Upgrades - Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform.	N/A
3.0.0	Overview The Cortex connector integrates with Cortex to synchronize the service catalog, teams, and people maintained in your Cortex organization. Category: System Management Models	N/A