> For the complete documentation index, see [llms.txt](https://docs.kosmoslabs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kosmoslabs.ai/product-documentation/integration-permissions.md).

# Integration Permissions

How Kosmos connects to your systems securely

***

Kosmos uses read-only API connections to analyze your data. We never install code in your environment or modify your systems.

### Our Security Approach

**Zero-Install Architecture** Kosmos operates entirely outside your infrastructure. We connect through each vendor's standard authorization mechanism: OAuth for most systems, a marketplace app where the vendor requires one (a managed package for Salesforce, a GitHub App for GitHub). Nothing runs inside your environment.

**Read-Only Access** We request only the minimum permissions needed to analyze your data. Kosmos cannot create, update, or delete records in your systems.

**No Code Deployment** No Kosmos code executes in your Salesforce org, Jira instance, or GitHub repositories. This means:

* No security reviews of deployed packages
* No impact on your system performance
* No maintenance burden on your team

***

### Permissions by Integration

#### Salesforce Service Cloud

**Setup Required:** Salesforce requires installing our managed package before connecting. See [Connecting Salesforce](/product-documentation/connecting-salesforce.md) for step-by-step instructions.

| Permission         | Why We Need It                                       |
| ------------------ | ---------------------------------------------------- |
| Read Cases         | Analyze incident and support ticket patterns         |
| Read Case Comments | Understand resolution context                        |
| Read Case History  | Reconstruct incident timelines                       |
| Read Incidents     | ITSM correlation (if Service Cloud Incident enabled) |
| Read Users         | Attribute incidents to teams                         |

**What we DON'T access:** Opportunities, financial data, custom objects (unless mapped), attachments, or files.

**Case fields shown on signals:** Kosmos surfaces each case's **Type**, **Origin**, and **Owner** directly on the signal, using the same Read Cases and Read Users access above. If your organization maps a custom Product field, that appears too.

**Salesforce Error Monitoring (Preview):** An optional collector that watches your Salesforce org's own audit trail, Data Cloud, event log files, Apex exceptions, and governor limits for errors, so Kosmos can correlate Salesforce-side failures alongside your other signals. Tenant owners and managers can turn it on from the Salesforce integration settings, choose which of the five sources to collect, and set a collection interval from 30 minutes to 7 days. Each source's status (succeeded, partial, failed, or off) reflects its last collection cycle. Available on the same plan as OpenTelemetry ingestion. For setup, sources, intervals, and status, see [Connecting Salesforce](/product-documentation/connecting-salesforce.md#optional-salesforce-error-monitoring-preview).

**Salesforce change records:** The audit trail source also lets Kosmos treat qualifying Setup changes as changes it can correlate with errors, the way it treats deployments from source control. Setup Audit Trail entries for Apex class and trigger changes, managed package installs and upgrades, and change set deployments become change records, stored alongside your Git deployments.

* **Production only:** A change record from a production org can be the change a Risk Event is correlated to. A sandbox connection's records are never treated as production changes.
* **Git deployments take precedence:** When a Git deployment covers the same component within 10 minutes, Kosmos links the error to the Git deployment, so the commit, pull request, and CI evidence stays in the Risk Event.
* **Packages:** An error from a managed package links to that package's upgrade through the package namespace. An error that occurred shortly before a change never links to it, even if it occurs again afterward.
* **Jira keys:** A change set whose name contains a Jira issue key links to that issue.
* **RCA Reports:** A change record shows its kind (Setup change, package upgrade, or change set), its components (up to 20), and when it happened, with no CI status.

As with every correlation, a Risk Event built on a change record becomes an official root cause only when a human confirms it in Kosmos.

***

#### Jira

| Permission              | Why We Need It                            |
| ----------------------- | ----------------------------------------- |
| Read Issues             | Analyze bugs, incidents, and tasks        |
| Read Projects           | Understand team structure                 |
| Read Comments           | Context for root cause analysis           |
| Write Issues (optional) | Create follow-up tickets from RCA Reports |

**What we DON'T access:** Confluence pages, admin settings, user passwords, or billing information.

**Note:** Write access is only used when you explicitly click "Create Jira Ticket" from an RCA. Kosmos never creates tickets automatically.

***

#### GitHub

**Setup Guide:** See [Connecting GitHub](/product-documentation/connecting-github.md) for step-by-step instructions.

Kosmos connects through the **Kosmos GitHub App**, which your organization installs on the repositories you choose. Every permission below is read-only. The app requests no write permission on any resource, so Kosmos cannot modify anything in your repositories even in principle.

| Permission    | Level | Why We Need It                                                                                   |
| ------------- | ----- | ------------------------------------------------------------------------------------------------ |
| Metadata      | Read  | Repository and branch metadata; detects your default branch to prefill production branch mapping |
| Contents      | Read  | Commits and releases, to correlate deployments with incidents                                    |
| Pull requests | Read  | Identify changes linked to issues                                                                |
| Issues        | Read  | Issues, comments, and labels as incident signals                                                 |
| Deployments   | Read  | Deployment events and their environment, for production attribution                              |
| Projects      | Read  | Only requested if project sync is enabled for your organization                                  |

**What we DON'T access:** We have no write permission on anything. We do not read secrets, Actions logs, or organization admin settings, and we do not manage webhooks or deploy keys.

**Repository scope:** At install time your admin chooses **All repositories** or **Only select repositories**. Kosmos can only see what the installation includes. The repository picker inside Kosmos lists exactly those repositories, so what you see in Kosmos matches the access you actually granted. You can change the selection in GitHub at any time without reconnecting.

**Choosing what to sync:** Within your installation, search and select the specific repositories you want Kosmos to actively sync from Settings → Integrations → GitHub. If you clear the selection entirely, Kosmos syncs none of your GitHub repositories until you select at least one again.

**Authentication:** The Kosmos GitHub App authenticates with short-lived installation tokens that Kosmos mints and refreshes automatically. There is no long-lived token sitting in our database waiting to be revoked. If the installation is uninstalled or suspended, the integration moves to a needs-re-authentication state and syncing stops.

**Legacy connections:** Kosmos's GitHub integration now authenticates exclusively through the Kosmos GitHub App; the older OAuth-based connection method has been fully retired. If your organization is still on that older connection, the GitHub card shows it as needing reconnection. Reconnecting installs the GitHub App and lets you choose exactly which repositories it can see, the same as a first-time connection.

**Production branches:** During setup, after you select repositories, Kosmos asks you to confirm which branches represent production for each repo. The detected default branch (usually `main`) is prefilled, and you can adjust it if your team ships from a differently named branch such as `develop`.

This mapping tells Kosmos which deployments reached production. Kosmos uses the strongest signal available for each deployment event: an explicit environment from the GitHub Deployments API if present, otherwise your branch mapping. Getting the mapping right means Risk Events reflect changes that actually reached your customers rather than treating every merge as a production deploy.

You can revisit the mapping later from Settings → Integrations → GitHub.

***

#### Bitbucket

| Permission                   | Why We Need It                                                  |
| ---------------------------- | --------------------------------------------------------------- |
| Read Commits                 | Correlate deployments with incidents                            |
| Read Pull Requests           | Identify changes linked to issues                               |
| Read Repositories (metadata) | Understand codebase structure                                   |
| Read Branches (metadata)     | Detect your default branch to prefill production branch mapping |

**What we DON'T access:** Source code contents, pipeline secrets, or admin settings.

**Note:** Search and select the specific repositories you want Kosmos to sync from Settings → Integrations → Bitbucket. If you clear the selection entirely, Kosmos syncs none of your Bitbucket repositories until you select at least one again.

**Production branches:** Bitbucket setup includes the same production branch confirmation step described under GitHub above. For Bitbucket, Kosmos will also use a pipeline deployment step name when one is present, before falling back to your branch mapping.

***

#### GitLab

**Setup Guide:** See [Connecting GitLab](/product-documentation/connecting-gitlab.md) for step-by-step instructions. Both GitLab.com and self-managed instances are supported.

| Permission               | Why We Need It                              |
| ------------------------ | ------------------------------------------- |
| Read Issues              | Analyze issues as incident signals          |
| Read Merge Requests      | Identify changes linked to issues           |
| Read Commits             | Correlate deployments with incidents        |
| Read Pipelines           | Correlate pipeline runs with incidents      |
| Read Deployments         | Attribute deployment events to environments |
| Read Projects (metadata) | Scope sync to selected projects             |

**Authentication:** GitLab uses OAuth 2.0. You'll be redirected to your GitLab instance to authorize the connection. Access tokens expire every two hours and Kosmos refreshes them in the background.

**What we DON'T access:** Source code contents, CI/CD variables and secrets, container registries, admin settings, or billing information.

**Note:** You can search and restrict sync to specific projects and choose which data types to sync from Settings → Integrations → GitLab after connecting. If you clear the project selection entirely, Kosmos syncs no GitLab issues until you select at least one project again.

***

#### ServiceNow

| Permission           | Why We Need It                   |
| -------------------- | -------------------------------- |
| Read Incidents       | Analyze ITSM incident patterns   |
| Read Change Requests | Correlate changes with incidents |

**What we DON'T access:** CMDB data, knowledge articles, admin settings, or user credentials.

**Field Mapping:** After connecting, you can map your custom ServiceNow fields to Kosmos. This ensures RCAs include context from your organization's specific incident data.

**Sandbox Support:** You can connect a sandbox instance (dev/test/uat) for evaluation before granting production access.

***

#### Zendesk

| Permission         | Why We Need It                              |
| ------------------ | ------------------------------------------- |
| Read Tickets       | Analyze support ticket patterns             |
| Read Custom Fields | Include your organization's ticket metadata |

**What we DON'T access:** User passwords, billing information, admin settings, or Guide/Help Center content.

***

#### Pylon

| Permission               | Why We Need It                                   |
| ------------------------ | ------------------------------------------------ |
| Read Issues              | Analyze support issues and tasks                 |
| Read Messages (optional) | Include conversation context for deeper analysis |

**Authentication:** Pylon uses API key authentication. You provide your Pylon API key when connecting.

**What we DON'T access:** Internal notes marked private, billing data, or admin settings.

**Note:** Search and select the specific accounts and teams you want Kosmos to sync from Settings → Integrations → Pylon. If you clear either selection entirely, Kosmos syncs nothing for Pylon until you select at least one account and team again.

***

#### Linear

| Permission               | Why We Need It                                          |
| ------------------------ | ------------------------------------------------------- |
| Read Issues              | Analyze bugs and tasks as incident signals              |
| Read Issue State         | Understand resolution status and workflow stage         |
| Read Issue Labels        | Classify issues by type and priority                    |
| Read Teams               | Scope sync to selected teams; understand team structure |
| Read Assignees           | Attribute issues to team members                        |
| Read Relations           | Link related issues for cross-reference correlation     |
| Read Attachments         | Extract linked Jira and GitHub issue keys               |
| Read Comments (optional) | Include conversation context for deeper analysis        |

**Authentication:** Linear uses OAuth 2.0. You'll be redirected to Linear to authorize the connection.

**What we DON'T access:** Cycles, roadmaps, projects, documents, admin settings, or billing information.

**Note:** You can search and restrict sync to specific teams from Settings → Integrations → Linear after connecting. If you clear the team selection entirely, Kosmos syncs no Linear issues until you select at least one team again.

***

#### Azure DevOps

| Permission                         | Why We Need It                                             |
| ---------------------------------- | ---------------------------------------------------------- |
| Read Work Items                    | Analyze bugs, issues, and tasks as incident signals        |
| Read Work Item Types               | Understand item classification across process templates    |
| Read Work Item Comments (optional) | Include conversation context for deeper analysis           |
| Read Projects                      | Scope sync to selected projects; understand team structure |
| Read Teams                         | Attribute work items to teams                              |

**Authentication:** Azure DevOps uses OAuth 2.0 via Microsoft Entra. You'll be redirected to Microsoft to authorize the connection.

**What we DON'T access:** Source code, repositories, pipelines, test plans, wiki pages, admin settings, or billing information.

**Note:** You can restrict sync to specific projects and work item types from Settings → Integrations → Azure DevOps after connecting.

***

#### OpenTelemetry (Preview)

**Setup Guide:** See [Connecting OpenTelemetry](/product-documentation/connecting-opentelemetry-preview.md) for step-by-step configuration instructions.

Kosmos can ingest OpenTelemetry data to correlate observability signals (traces, logs, metrics) with your incidents and deployments.

| Data Type | Why We Need It                          |
| --------- | --------------------------------------- |
| Traces    | Correlate service errors with incidents |
| Logs      | Identify error patterns and anomalies   |
| Metrics   | Detect performance degradation          |

**Authentication:** API key authentication. Generate a unique API key from Settings → Integrations → OpenTelemetry.

**Setup:** Configure your OpenTelemetry Collector to export to the Kosmos OTLP endpoint. Example configs provided for Grafana Agent, Datadog Agent, and generic OTLP exporters.

**Preview Status:** This integration is in Preview. Core functionality is stable, but we're actively refining the experience based on customer feedback.

***

#### Slack / Microsoft Teams (Notifications)

| Permission    | Why We Need It                                            |
| ------------- | --------------------------------------------------------- |
| Post Messages | Send Risk Event and RCA alerts to your configured channel |

**What we DON'T access:** Message history, user data, private channels, or any channel other than the one you configure.

**Note:** Notification integrations are optional. You can use Kosmos without connecting Slack or Teams. Integration health alerts (disconnect and reconnect notifications) are currently sent via Slack only; Teams support for these alerts is not yet available.

***

### Who Can Manage Integrations

**Only workspace owners and managers can change integration connections and sync settings.** Connecting, reconnecting, disconnecting, running **Sync now**, and changing sync settings (including Salesforce field mapping) are limited to owners and managers. Standard members get a view-only **Integrations** page.

A standard member sees the same cards, connection states, and sync status as an owner or manager. The differences are:

* A **Viewer** badge appears next to the page title.
* A banner states that the page is view-only and lists up to three owners and managers to contact. If there are more, it shows how many and links to Team settings.
* Controls that change something are disabled, not hidden. Hover over, tap, or focus a disabled control to see why.
* **Configure** becomes **View settings**. The sync settings dialog opens with the current settings and every input disabled.
* The Slack and Microsoft Teams connect, configure, and disconnect controls, and the OpenTelemetry API key controls, are also disabled.

If a standard member's change is refused anyway, Kosmos shows a message that they don't have permission to change integrations.

To change an integration, ask one of the listed owners or managers.

***

### Data Handling

* **Encryption:** All data encrypted in transit (TLS 1.3) and at rest (AES-256)
* **Retention:** Data retained only while your account is active
* **Location:** Hosted on Google Cloud Platform (US regions)
* **Compliance:** SOC 2 Type 1 report available on request; SOC 2 Type 2 in progress; DPA available upon request

### Revoking Access

You can disconnect any integration at any time from Settings → Integrations. Revoking access immediately stops data sync. To request data deletion, contact <support@kosmoslabs.ai>.

### Questions?

If your security team needs additional documentation, we're happy to provide:

* Security questionnaire responses
* Data Processing Agreement (DPA)
* Architecture diagrams

Contact your Kosmos team or email <security@kosmoslabs.ai>.

***

**Questions?** Contact <support@kosmoslabs.ai> | [app.kosmoslabs.ai](https://app.kosmoslabs.ai)

© 2026 Kosmos AI Labs, Inc.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kosmoslabs.ai/product-documentation/integration-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
