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

# Integrations (overview)

> Olyros plugs into the tools your team already uses.

An integration is a company-scoped connection to an outside system. Each one holds its
own credentials, encrypted at rest, a status with the last error seen, and the inbound
or outbound paths it enables: events that start [workflows](https://user-docs.olyrosstudios.com/workflows.md) or agent
tasks, and actions that write back. The hub is the sidebar entry **Integrations** in the
**Settings** group (`/integrations`), with GitHub connections at
`/integrations/github/:connectionId`, Jira connections at `/integrations/jira/:connectionId`,
provider and custom integrations at `/integrations/:integrationId`,
`/integrations/generic/new` and `/integrations/generic/:integrationId/edit`. MCP servers
sit in the **Agents** group (`/settings/mcp-servers`) and Slack people and groups in the
**Settings** group (`/settings/slack-users`, `/settings/slack-groups`). Each kind has its
own page below.

## What it does

| Integration | What it connects | Inbound | Outbound | Page |
| - | - | - | - | - |
| GitHub | A GitHub App installation per organisation; repositories with `none` / `read` / `read_write` access | Issues become agent tasks; PR, push and issue events start workflows | Issues, labels, comments; repository tokens for tasks and sandboxes | [github.md](https://user-docs.olyrosstudios.com/github.md) |
| Jira Cloud | One site per company by OAuth; monitored projects | Issue created, updated and deleted events start workflows | Issues, comments, labels, transitions | [jira.md](https://user-docs.olyrosstudios.com/jira.md) |
| Slack | One workspace; one Slack app per agent, or one [router](https://user-docs.olyrosstudios.com/routers.md) app in front of many agents | Mentions in listed channels and DMs start agent conversations; button clicks | Agent replies, workflow messages, App Home | [slack.md](https://user-docs.olyrosstudios.com/slack.md) |
| MCP servers | The company's own remote tool servers | — | Tool calls from agents, with static secret or per-person OAuth | [mcp-servers.md](https://user-docs.olyrosstudios.com/mcp-servers.md) |
| Generic and provider integrations | Model and content provider API keys; custom HTTP APIs | — | Agent model calls, HTTP API tools, content ingestion | [generic-integration.md](https://user-docs.olyrosstudios.com/generic-integration.md) |

**Common model.** Every connection is a row scoped to the company with encrypted
secrets (one platform-managed key set shared by all credential types), a status enum, a
`last_error`, and timestamps for the last webhook or test. Two connections share the
provider-agnostic pieces: `SourceSystem` (`github`, `jira`) for ticket systems, and
`AgentTriggerType` (`label_pattern`, `custom_field`, `yaml_front_matter`) plus the
`agent:` label prefix for naming an agent on a ticket. Only GitHub reads a trigger
setting; Jira has none, and Jira events reach agents through workflows with a JIRA
Event trigger.

**Inbound webhooks.** Each system has its own public endpoint that never requires a login.
GitHub, Jira and Slack go through one ingress path
that verifies the sender and maps it to exactly one company before any handler runs;
nothing in the payload picks the company. GitHub (`/api/github/webhooks`, App HMAC, the
installation's single connection row), Jira (`/api/jira/webhooks/{token}`, the
per-connection URL token; the untokenized `/api/jira/webhooks` answers 410), Slack
(`/api/slack/events`, `/api/slack/interactions`, signing secret, the connected workspace),
Stripe for billing (`/api/webhooks/stripe`), and the **generic workflow webhook**
(`POST /api/webhooks/workflow/{token}`) that any external sender can call with optional
HMAC signature and header token, a payload cap, delivery logging and replay (details in
[workflows.md](https://user-docs.olyrosstudios.com/workflows.md)).

**Install and connect links.** Starting a GitHub install, a Jira connect or a Slack app
install issues a single-use state bound to the company and the person who started it,
valid for ten minutes. The callback refuses an expired or reused
state and re-checks that the person is still a member before anything is stored.

**Platform prerequisites.** The GitHub App and the Atlassian OAuth app are configured
once by a platform admin in the admin app (`/integrations/github`,
`/integrations/jira`); companies then install or connect them.

## Who can use it

Roles differ per integration and are listed on each page. The gates are named abilities
from the catalogue, shown under **Settings -> Roles** (`/settings/roles`) and on
[Company settings](https://user-docs.olyrosstudios.com/company-settings.md).

| Ability | Role | Covers |
| - | - | - |
| `integration.manage` | editor or admin | Connect, verify, disconnect and rewire GitHub and Jira (webhooks, repository refresh and access, trigger settings); create an agent's Slack app and set its channels |
| `integration.manage_providers` | company admin | Create, edit and test provider and custom integrations and their credentials |
| `mcp.manage` | company admin | Add, edit and remove MCP servers, bind them to agents, see everyone's connections |
| `slack.manage` | company admin | Link, tag and remove Slack users, manage Slack groups, access audits, activity exports, App Home upgrades |

Reading connections, deliveries and Jira metadata, the Slack workspace tokens, deleting a
provider integration and starting your own MCP sign-in are open to any company member.
Platform app configuration is for platform admins. No plan or tier gate exists.

## How to configure it

Open Settings -> Integrations (`/integrations`) and follow the page for the kind you need. Order that
avoids dead ends: provider integrations first (agents need a model), then GitHub or Jira
(for tasks and workflows), then Slack (for conversations), then MCP servers (for tools).

## Limits and defaults

See the per-integration pages. Shared:

| Setting | Value | Where enforced |
| - | - | - |
| Credential encryption | encrypted at rest with a platform-managed key | credential model |
| Install and connect links | single use, 10 minutes (Slack 600 s signed state; GitHub and Jira one-shot rows) | link state |
| Webhook to company mapping | one verified row per installation, token or workspace | webhook ingress |

## What it emits

Webhook delivery logs (GitHub, Jira, workflow webhooks), workflow runs, agent tasks with
external issue links, outbound Slack messages, MCP credential use, provider usage
statistics.

## Known gaps

* No outbound generic webhook or email action; outbound is Jira, GitHub, Slack and
  tool calls.
* Jira issues do not become tasks without a workflow, unlike GitHub issues.
* One Slack workspace per company at a time; one GitHub installation belongs to one
  company only.
* Gates are uneven across integrations (admin for MCP and providers, editor for GitHub,
  Jira and Slack app wiring, any member for the Slack workspace tokens and for deleting a
  provider integration).

## Customer-safe summary

Olyros plugs into the tools your team already uses. It connects to GitHub for code and
issues, Jira for tickets, Slack for conversation, your own MCP tool servers, and the model
and API providers you rely on. Each connection is set up once, kept secure with encrypted
credentials, and shows its health and recent activity so you always know it is working.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.