Connect apps to Cortex

Connections let Cortex read your company's own content — repositories, issues, pages and messages — so the activity Cortex Sensor captures sits next to the work it refers to.

A connection applies to the whole Cortex organization. An organization admin with app-configuration access sets it up once, and there is nothing for colleagues to do. Give Cortex access only to content that everyone in the Cortex organization is allowed to use.

Capture does not depend on any of this. Cortex Sensor captures AI activity whether or not an app is connected; connections add the company context that activity refers to.

Where to connect apps

Open Organization → Apps. This is the complete path for adding, testing, configuring, reauthorizing, revoking and deleting connections. If you administer more than one organization, the same tab sits under Admin → Organizations, on the organization you are configuring.

Each row names the app, its Subject — Whole org for every self-service connection — whether a Credential is Set, and its Status. Status carries two lines: the connection is active or revoked, and the authorization underneath is Ready, Verification required, Reauthorization required, Unsupported or Status unavailable. A connection waiting on reauthorization offers Reauthorize instead of Test & preview.

Test & preview is the check to run after every change. It reports connection health and a bounded sample of what Cortex can see — capped, and never showing credentials, internal IDs, URLs, descriptions or raw provider payloads.

Apps can also be connected during onboarding. After onboarding, return to Organization → Apps to run Test & preview and finish any app-specific configuration.

GitHub

What you need: someone allowed to install GitHub Apps for the GitHub organization.

1. In Cortex, open Organization → Apps and add GitHub.
2. Continue to GitHub and install the Cortex GitHub App for the GitHub organization. Personal GitHub accounts are not supported.
3. During installation, choose the repositories Cortex may access.
4. Complete the GitHub authorization step and return to Cortex.
5. Select Test & preview. The preview lists repositories from the installed organization.

If you cannot install GitHub Apps yourself

Select Send GitHub owner link at the top of Apps and enter the organization's URL handle — the acme in github.com/acme, letters, numbers and hyphens only. A display name is rejected. Cortex generates a link restricted to that one organization, valid for 72 hours. Send it to a GitHub owner, who does not need a Cortex account.

How access works

Cortex stores the GitHub App installation, not a GitHub user's access token. Repository access follows the repositories chosen for that installation, so widening or narrowing it is a change you make in GitHub.

Jira

What you need: an Atlassian account that can reach the Jira site to connect.

1. In Cortex, open Organization → Apps and add Jira.
2. Sign in to Atlassian and approve read access to Jira work and Jira users, plus offline access so the connection can stay active.
3. If the account can reach more than one site, choose the Jira site to connect.
4. Return to Cortex and select Test & preview. The preview lists non-archived projects from that site.

Jira scope and limits

One connection covers one Jira site and is read-only. Cortex asks Atlassian for Jira work and Jira user read access plus offline access, and nothing else.

If the Jira connection stops working

When Atlassian invalidates the authorization, Cortex marks the connection for reauthorization. Select Reauthorize in Apps.

Linear

What you need: a Linear account that can reach the workspace to connect.

1. In Cortex, open Organization → Apps and add Linear.
2. Sign in to Linear and approve read access. The grant includes a refresh, so the connection can stay active.
3. Linear returns to Cortex and the connection completes. One authorization reaches exactly one workspace, so there is nothing to choose.
4. Select Test & preview. The preview lists teams and projects from that workspace.

Linear scope and limits

One connection covers one Linear workspace and every team in it, and is read-only. Cortex reads Linear as the account that authorized it, so it sees only the issues that account can see.

If the Linear connection stops working

When Linear invalidates the authorization, Cortex marks the connection for reauthorization. Select Reauthorize in Apps.

Notion

What you need: permission to create a Notion internal integration and to manage the pages it can read.

1. In Notion, create an internal integration for the workspace.
2. Enable the integration's Read content capability.
3. Share only the pages that are safe for the whole Cortex organization with that integration. A new internal integration has no page access until pages are shared with it, and sharing a parent page shares its child pages too.
4. Copy the integration token from Notion.
5. In Cortex, open Organization → Apps, add Notion, and paste it into Internal integration token.
6. Select Test & preview. The preview lists the pages the integration can access.

Choose which pages Cortex reads

Select Configure pages to open Configure Notion pages. Keep All pages shared with the integration, or choose Only selected pages to narrow it further. That list comes from the existing Notion connection, so run Test & preview first if it looks out of date.

Slack

What you need: permission to create and install a Slack app in the workspace. Slack takes two stages — configure the Slack app first, then connect it to Cortex.

Stage 1: configure the Slack app in Slack

Create a Slack app for the workspace. Under OAuth & Permissions, add these Bot Token Scopes:

channels:history
channels:read
groups:read
im:read
mpim:read
users:read
users:read.email

Cortex rejects a bot token that is missing any of them. im:read and mpim:read are required even though Cortex does not read direct messages: Slack fails the whole channel-list call if a requested conversation type lacks its scope, which returns an empty channel list rather than an error.

Slack's message search accepts a user token only, so add these User Token Scopes if you want Slack results in Search:

search:read
users:read.email

Then finish the Slack app:

1. Enable Socket Mode.
2. Enable Event Subscriptions and subscribe to the message.channels and message.groups bot events.
3. Create an app-level token with the connections:write scope.
4. Install the app to the workspace. If you change scopes after installing, reinstall it.
5. Copy the bot token (xoxb-…), the app-level token (xapp-…), and the user token (xoxp-…) if you configured one.

Stage 2: connect Slack to Cortex

1. In Cortex, open Organization → Apps and add Slack.
2. Enter the bot token in Bot token and the app-level token in App-level token (optional). Add the search user token under Search user token (optional) if you created one.
3. Select Test & preview and confirm the expected Slack workspace.
4. Select Configure channels and enable the public channels Cortex should use.

The search user token is the genuinely optional one. Without it, channel capture works and Slack results do not appear in Search.

What Search returns

Organization-wide Search returns public-channel content. Direct messages and private-channel messages are not shown in organization-wide Search.

In Slack channels, ingest state is on each row. Turning ingest off hides that channel from Search and Ask.

Manage an existing connection

Everything after setup happens in Organization → Apps:

• Run Test & preview after any change made in the app itself.
• Update app-specific settings, such as Configure pages or Configure channels.
• Select Reauthorize when Jira or Linear asks for it.
• Select Revoke to stop future use of a connection.
• Select Delete to remove a connection.

Selecting Edit connection on Notion or Slack reopens its token fields. Each token Cortex already holds reads Stored with a Remove action, and no field shows a value — paste only the tokens you are changing.

Hand a task to an agent

Select a prompt to copy it, then give it to a coding agent together with this page.

• Walk me through connecting GitHub to Cortex for the GitHub organization ORG-NAME, and tell me what Test & preview should list when it worked.
• Our Jira connection is marked for reauthorization. Explain what that means and the exact steps to fix it in Cortex.
• List the Slack bot token scopes Cortex requires and explain what breaks if the app-level token is missing.
• Our Notion preview lists fewer pages than expected. Explain how Notion page sharing decides what Cortex can read, and what to check.

Get help

Contact the Chaos Labs team when a connection cannot be authorized, or when Test & preview does not list what you expect. Include the app, the Cortex organization and the approximate attempt time. Never include a token value.