# Integration authentication requirements

import { Aside } from '@astrojs/starlight/components';

EkLine Docs Agent connects to the tools your team already uses — source control, issue trackers, knowledge bases, and chat — to gather context and publish documentation. Before you approve a connection, review what it grants. This reference covers every integration the agent supports: the authentication method, the account role needed to connect it, whether the agent reads or writes, and the exact scopes each connection requests.

## How authentication works

Docs Agent connects to your tools with one of three methods. In every case, you authorize the connection — EkLine never asks for a user password.

| Method | How you authorize | What EkLine receives |
|--------|-------------------|----------------------|
| OAuth 2.0 | You approve the connection on the provider's authorization screen, which lists the exact permissions EkLine requests. | A scoped authorization the provider issues. Revoke it anytime from the provider or from EkLine. |
| Access token or API key | You create a scoped token in the provider and paste it into EkLine. | The token you created, with the scopes and role you granted it. |
| GitHub App | You install the EkLine GitHub App on the repositories you select. | Short-lived installation tokens that GitHub issues for those repositories. |

<Aside type="note" title="You approve the exact scopes">
For OAuth 2.0 integrations, the provider's authorization screen shows the exact scopes EkLine requests before you approve. Review that screen at connection time, and match it against the [scope tables](#oauth-integration-scopes) below.
</Aside>

## Data access and permissions

These principles apply to every integration:

- **The agent inherits the connecting account's permissions.** Docs Agent can only read or change content that the authorizing account can already access. It cannot reach anything that account cannot.
- **Connections are organization-level.** An administrator connects an integration once, and members use it inside Docs Agent sessions. The agent acts with the permissions of the account that authorized the connection.
- **You choose the scope.** Select the specific repositories, spaces, or knowledge bases the agent can work with. Content you do not select stays out of reach.
- **Credentials are stored encrypted.** EkLine stores integration tokens and connection credentials encrypted at rest.
- **Read and write access is explicit.** The **Data access** column shows the level each connection is granted. Several integrations are granted write access. The [scope tables](#oauth-integration-scopes) list exactly what every connection requests, so your reviewers can see each permission.

<Aside type="tip" title="Use a service account for Atlassian">
For Jira, Confluence, and Atlassian Teamwork Graph, connect a dedicated Atlassian service account rather than an individual's account. A service account keeps the connection working when a team member changes roles or leaves. It scopes access to only the spaces the agent should reach and makes activity easy to audit under a recognizable name such as `EkLine AI`.
</Aside>

## Supported integrations

Integrations marked † are enabled on request. Contact support@ekline.io to turn them on for your organization.

| Integration | Authentication | Role required to connect | Data access | How Docs Agent uses it |
|-------------|----------------|--------------------------|-------------|------------------------|
| GitHub | GitHub App installation | GitHub organization owner | Read and write | Reads repository code and pull requests for context, commits changes to open documentation pull requests, and posts or updates pull request comments. |
| GitLab | Access token (group, project, or personal) with the `api` and `read_repository` scopes | Group Owner for a group token, or a member who can create a token with both scopes | Read and write | Reads merge requests, issues, and repository files, commits changes, and opens merge requests in your documentation projects. |
| Jira | OAuth 2.0 | A member with access to the projects, or an Atlassian service account | Read and write | Reads issue titles, descriptions, and comments to update documentation or generate release notes. Jira auto-trigger † manages a webhook so the agent can start updates when an issue changes. |
| Linear | OAuth 2.0 | A member with access to the issues | Read and write | Reads issue titles, descriptions, and comments to update documentation or generate release notes. |
| Confluence | OAuth 2.0 | An Atlassian account with access to the spaces, ideally a service account | Read and write | Reads pages and spaces as source material. With knowledge base management †, updates managed pages and their images and publishes changes back to Confluence. |
| Notion | OAuth 2.0 | A member with access to the pages | Read and write | Reads pages and databases, such as product specs and design documents, as source material. |
| Google Drive | OAuth 2.0 | A member with access to the files | Read and write | Searches, reads, creates, uploads, and organizes files and folders on behalf of the connecting account. |
| Slack | OAuth 2.0 (workspace app installation) | Slack workspace owner or administrator | Read and write | Reads channel, group, and direct message threads as source material, then posts drafts and diffs, adds reactions, and uploads files in reply. |
| PostHog | Personal API key with a selected region | A member who can create a personal API key | Read | Reads insights, HogQL query results, and feature flag configurations to ground release notes and feature documentation in usage data. |
| Pylon | API token | An administrator who can generate a Pylon API token | Read and write | Reads, updates, and creates help center articles, and publishes changes back to Pylon. |
| Atlassian Teamwork Graph | Atlassian API token, ideally a service-account token | An Atlassian administrator who can create a service-account token with read and search access | Read only | Searches your whole Confluence site to find source material across every space the account can access. It never writes back. |

## GitHub App permissions

The EkLine GitHub App requests these repository and organization permissions. GitHub shows the exact set on the installation screen before you approve it.

| Permission | Access | Why the app needs it |
|------------|--------|----------------------|
| Contents | Read and write | Read repository files for context and commit documentation changes on a new branch. |
| Pull requests | Read and write | Read pull request details and open, update, and comment on documentation pull requests. |
| Issues | Read and write | Post and update comments, add labels, and react on pull request threads. |
| Metadata | Read | Baseline access GitHub requires for every app. |
| Organization members | Read | Confirm that a requester belongs to the connected organization. |

You choose which repositories the app can access when you install it — either all repositories or a selected list. EkLine acts only on the repositories you add under **Documentation Repositories** or **Code Repositories**.

## OAuth integration scopes

For OAuth 2.0 integrations, EkLine requests the scopes below. The provider lists them on its authorization screen when you connect, and the connecting account's own permissions still bound what the agent can reach. A scope grants a capability — it does not mean the agent uses it in every session.

### Slack

Bot-token scopes granted when you install the app on your workspace:

| Scope | What it permits |
|-------|-----------------|
| `channels:read`, `channels:history` | List public channels and read their messages. |
| `groups:read`, `groups:history` | List private channels the bot is in and read their messages. |
| `im:read`, `im:history` | List direct message conversations and read them. |
| `mpim:read`, `mpim:history` | List group direct messages and read them. |
| `app_mentions:read` | Receive messages that mention the app. |
| `metadata.message:read` | Read message metadata. |
| `chat:write` | Post messages as the bot. |
| `reactions:read`, `reactions:write` | Read and add emoji reactions. |
| `files:read`, `files:write` | Read files shared in conversations and upload files. |
| `users:read` | Read workspace member profiles. |
| `users:read.email` | Read member email addresses. |
| `team:read` | Read workspace metadata. |

### Jira

| Scope | What it permits |
|-------|-----------------|
| `read:jira-work` | Read issues, comments, worklogs, and attachments. |
| `write:jira-work` | Create and edit issues, comments, and worklogs. |
| `read:jira-user` | Read user profiles and search for users. |
| `read:project:jira` | Read project metadata. |
| `read:issue-type-scheme:jira` | Read issue-type schemes. |
| `read:sprint:jira-software` | Read sprints. |
| `read:board-scope:jira-software`, `write:board-scope:jira-software` | Read and modify boards. |
| `manage:jira-project` | Administer projects, versions, and components. |
| `manage:jira-configuration` | Administer site-level Jira configuration. |
| `manage:jira-webhook` | Register and delete webhooks. The Jira auto-trigger † uses this to start a session when an issue changes. |
| `manage:jira-data-provider` | Register a data provider on the site. |
| `offline_access` | Keep the connection working after the access token expires. |

### Confluence

Confluence requests both the current granular scopes and Atlassian's older classic scopes.

| Scope | What it permits |
|-------|-----------------|
| `read:content:confluence` | Read content across the site. |
| `read:content-details:confluence` | Read detailed content information. |
| `read:content.metadata:confluence` | Read content metadata. |
| `read:page:confluence` | Read pages. |
| `read:blogpost:confluence` | Read blog posts. |
| `read:folder:confluence` | Read folders. |
| `read:custom-content:confluence` | Read custom content. |
| `read:attachment:confluence` | Read attachments. |
| `readonly:content.attachment:confluence` | Read content attachments. |
| `read:comment:confluence` | Read comments. |
| `read:template:confluence` | Read templates. |
| `read:label:confluence` | Read labels. |
| `read:space:confluence` | Read spaces. |
| `read:space-details:confluence` | Read space details. |
| `read:hierarchical-content:confluence` | Read hierarchical content, such as page trees. |
| `search:confluence` | Search content across the site. |
| `write:content:confluence` | Create and update content. |
| `write:page:confluence` | Create and update pages. |
| `write:blogpost:confluence` | Create and update blog posts. |
| `write:custom-content:confluence` | Create and update custom content. |
| `write:comment:confluence` | Create and update comments. |
| `write:label:confluence` | Add and remove labels. |
| `write:attachment:confluence` | Upload and update attachments. |
| `delete:attachment:confluence` | Delete attachments. |
| `read:audit-log:confluence` | Read the audit log. |
| `write:audit-log:confluence` | Write to the audit log. |
| `read:confluence-content.all` | Read all content (classic scope). |
| `read:confluence-content.summary` | Read content summaries (classic scope). |
| `read:confluence-space.summary` | Read space summaries (classic scope). |
| `write:confluence-content` | Create and update content (classic scope). |
| `offline_access` | Keep the connection working after the access token expires. |

### Notion

| Scope | What it permits |
|-------|-----------------|
| `read:user` | Read the connected account's Notion profile. |
| `read:content` | Read pages and databases the account can see. |
| `write:content` | Create pages and blocks. |
| `update:content` | Update existing pages and blocks. |

### Linear

| Scope | What it permits |
|-------|-----------------|
| `read` | Read issues, comments, projects, and teams. |
| `write` | Create and update Linear resources. |
| `issues:create` | Create issues. |
| `comments:create` | Create comments. |

### Google Drive

| Scope | What it permits |
|-------|-----------------|
| `https://www.googleapis.com/auth/drive` | Full read and write access to the files in the account's Drive. |
| `https://www.googleapis.com/auth/userinfo.email` | Read the account's email address. |

## Access token and API key scopes

These integrations connect with a token you create in the provider. You control the scopes and role when you create the token.

### GitLab

Create a group, project, or personal access token with both of these scopes. EkLine validates that both are present and rejects a token that is missing either.

| Scope | What it permits |
|-------|-----------------|
| `api` | Full read and write API access — repositories, merge requests, and issues — within the token's role. Docs Agent uses this to read content and to open merge requests. |
| `read_repository` | Read repository files over HTTPS. |

A group access token requires the Owner role to create. The token's role also bounds what it can do: choose the Developer role or higher so the agent can open merge requests in your documentation projects.

### PostHog

PostHog uses a personal API key rather than OAuth, so there is no EkLine-defined scope list. You create the key in PostHog, choose its scopes there, and paste the key and your region into EkLine. The key is only as broad as you make it, so grant it the minimum PostHog scopes the agent needs to read insights, run HogQL queries, and read feature flags.

### Pylon

Pylon uses an API token that an administrator generates in Pylon. The token carries the permissions of the Pylon account that created it. The agent reads, updates, and creates help center articles within those permissions.

### Atlassian Teamwork Graph

Teamwork Graph uses an Atlassian API token, ideally on a service account. Grant the account read and search access to only the Confluence spaces the agent should search. The connection is read-only — it searches and reads, and never writes back.

## Webhooks

GitHub and GitLab send events to EkLine over webhooks so the agent can react to pull requests, merge requests, and comments:

- **GitHub** verifies each delivery with a signed secret before EkLine processes it.
- **GitLab** verifies each delivery against a per-project secret token that EkLine generates and stores encrypted.

## Requesting access and revoking access

- **Requesting access.** Docs Agent is available on all plans on request. Contact support@ekline.io to enable Docs Agent, and to turn on any integration marked † above.
- **Revoking access.** Remove an OAuth connection from the provider or from **Settings > Organization > Integrations** in EkLine. Revoke an access token or API key in the provider to cut off a token-based integration, or uninstall the GitHub App from your GitHub organization settings.

## Related pages

- [Connect GitHub to EkLine Docs Agent](/agent/github-app-setup) — Install the GitHub App and select repositories.
- [Connect GitLab to EkLine Docs Agent](/agent/gitlab-setup) — Add a scoped access token and configure the webhook.
- [Connect Atlassian Teamwork Graph](/agent/teamwork-graph-setup) — Add an Atlassian API token for whole-site Confluence search.
- [Docs Agent integrations](/agent/integrations) — Reference content from each connected source in your prompts.
- [Manage a Confluence or Pylon knowledge base](/agent/manage-knowledge-base) — Let the agent update pages and publish changes back.