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

# Connect a tool

> Back one of an AI employee's tools with one of your saved connections.

From now on the tool's calls go to the vendor through the connection, after the same approvals as
before.

> [!WARNING]
>
> AI employees are in **beta**. Every route answers `404` unless your deployment has switched the
> beta on. See [AI employees](https://docs.mithunai.com/team/overview.md).

Connecting a tool never lets an employee act without a person where your policy says one is
needed. A connection of the same kind already on the tool is replaced. Requires owner or admin, and a
person: an API key is refused. Audited. Steps for making each token are in
[Connect your tools](https://docs.mithunai.com/team/connect-your-tools.md).

**role** `string` *required*

`support`, `itsm`, `devops`, `marketer`, `sales` or `finance`.

**tool** `string` *required*

One of the employee's tools whose `connectable_kinds` is not empty: `ticket_inbox` and `handoff`
(Support, `zendesk`, `freshdesk` or `intercom`, one at a time: `409` while another of the three is
attached), `ticketing` (IT service desk and DevOps, `atlassian`), `observability` (DevOps,
`grafana` and `github`), `chat` (Support, IT service desk and Finance, `slack`), `cms` (Marketer,
`wordpress`), `crm` (Sales, `hubspot`), `billing` (Finance, `stripe`), `identity` (IT service
desk, `okta`, `google_workspace` or `microsoft_entra`; Beta), `email` (Sales, `gmail` or
`microsoft_outlook`, one at a time; Beta).

**credential\_id** `string` *required*

One of your saved connections, of a kind the tool takes.

**options** `object`

Text values, by kind. `zendesk`, `freshdesk` and `intercom`: `reply_mode` -- `draft` (the default:
a reply is posted as an internal note for an agent to send) or `public`. `atlassian`:
`project_key` for new issues, `issue_type` (default `Task`), or `service_desk_id` with
`request_type_id` to raise Jira Service Management requests, and `resolve_status` (default
`Done`). `github`: `repository` (`owner/name`), and `environment` or `workflow` (a workflow file
name). `grafana`: `prometheus_uid` and/or `loki_uid`, and optionally `error_rate_query`,
`latency_query` and `logs_query`, where `$service` stands for the alert's service. `slack`:
`channel`, the one channel approved messages go to. `okta`, `google_workspace` and
`microsoft_entra`: `group_prefix` -- only groups whose name starts with it are offered and
granted, such as `app-`. `gmail` and `microsoft_outlook`: `mailbox`, the one address drafts are
saved in, and `send` -- `off` (the default) or `on`, when an approved draft may be sent from here
as its own approval. `hubspot`, `wordpress` and `stripe` take none.

> [!NOTE]
>
> Off by default. `principal_id` is only accepted while the deployment has switched on
> `MITHUNAI_AI_EMPLOYEES_PERSONAL_MAILBOXES`.

**principal\_id** `string`

A person of your organization (UUID) this attachment is for alone. Only the Sales `email` tool
takes one: when that person approves a follow-up it is drafted in their own mailbox, and everyone
else's goes to the organization's attachment, if any. Absent attaches for the organization.

## Response

What is now attached: `tool`, `kind`, `credential_id`, `credential_name`, `host`, `options`,
`attached_by`, `attached_at` and `principal_id` (`null` for the organization's own attachment). A tool that takes no connection of that kind, or a malformed option,
is `400`; a connection that is not yours is `404`.


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