> ## 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.

# Save a connection to Atlassian, Notion, Zendesk or GitHub

> Store your sign-in to a service a knowledge source reads. The token is stored encrypted and is never returned, by this response or any other.

Saves a connection: your organisation's sign-in to a service a knowledge source reads. The response describes the connection and **does not contain the token**; no endpoint ever returns it. To change the token later, use [Replace a token](https://docs.mithunai.com/api-reference/connections/rotate-connection.md). See [Saved connections](https://docs.mithunai.com/knowledge/connections.md).

You need the owner or admin role (`credential.manage`). The deployment must have a secrets key configured; without one this returns `503`. A name already used in your organisation returns `409`. An organisation holds at most 100 connections.

MITHUNAI does not test the token when you save it. A wrong token is reported by the first sync of a source that uses it, or by [testing the AI employee's tool](https://docs.mithunai.com/api-reference/employees/test-tool.md) it is connected to.

**name** `string` *required*

Your label for the connection, 1 to 120 characters, unique in your organisation.

**kind** `string` *required*

The service: `github`, `atlassian` (Confluence, Jira and Jira Service Management Cloud), `notion`,
`zendesk` (Zendesk Support tickets), `grafana`, `hubspot`, `wordpress`, `slack`, `stripe`, `okta`,
`google_workspace`, `microsoft_entra`, `freshdesk`, `intercom`, `sentry`, `pagerduty`, `datadog`,
`gmail` or `microsoft_outlook` (AI employees only).

**fields** `object` *required*

The service's own fields, all strings. A field the kind does not take is refused with `400`, and no
error message ever repeats a value you sent.

**github**

**token** `string` *required*

A GitHub personal access token that can read the repositories. Printable characters, no spaces,
at most 4,096.

**atlassian**

**site\_url** `string` *required*

Your Atlassian Cloud site, such as `https://your-company.atlassian.net`. One connection reads
that site's Confluence, Jira and Jira Service Management. Any page address on the site is
accepted and only the host is kept. It must be `https`, exactly one name under `atlassian.net`,
with no port. **It is fixed for the life of the connection**: the token is never sent anywhere
else.

**email** `string` *required*

The email address of the Atlassian account the token belongs to.

**api\_token** `string` *required*

An Atlassian API token (not a scoped one).

**notion**

**token** `string` *required*

The API token of a Notion internal connection.

**zendesk**

**site\_url** `string` *required*

Your Zendesk subdomain, such as `your-company`, or `your-company.zendesk.com`, or any address on
it; only the host is kept. It must be exactly one name under `zendesk.com`: a help centre on your
own domain is refused, because the API is not served there. **It is fixed for the life of the
connection**.

**email** `string` *required*

The email address of the Zendesk agent the token is used as.

**api\_token** `string` *required*

A Zendesk API token, from Admin Center under Apps and integrations, APIs, API tokens.

**freshdesk**

Used by the Support AI employee; no knowledge source reads through it.

**site\_url** `string` *required*

Your Freshdesk domain, such as `your-company`, or `your-company.freshdesk.com`, or any address on
it; only the host is kept. It must be `https`, exactly one name under `freshdesk.com`, with no
port: a portal on your own domain is refused. **It is fixed for the life of the connection**.

**token** `string` *required*

The API key of the Freshdesk agent the employee posts as, from Profile settings. Printable
characters, no spaces and no colon.

**intercom**

Used by the Support AI employee; no knowledge source reads through it.

**token** `string` *required*

An Intercom access token, from your app's Authentication page in the Developer Hub.

**region** `string`

Where the workspace is hosted: `us` (the default, `api.intercom.io`), `eu`
(`api.eu.intercom.io`) or `au` (`api.au.intercom.io`). It picks the one host the token is sent
to, is returned as the connection's `host`, and **is fixed for the life of the connection**.

**hubspot, slack and stripe**

Used by AI employees; no knowledge source reads through them.

**token** `string` *required*

HubSpot: a private app's access token, starting `pat-`. Slack: a bot token, starting `xoxb-`.
Stripe: a restricted key, starting `rk_`. A Stripe secret key is refused.

**wordpress**

Used by the Marketer AI employee; no knowledge source reads through it.

**site\_url** `string` *required*

The site's own https address. Only the host is kept, and **it is fixed for the life of the
connection**. Plain http, another port, an address literal and a site in a subfolder are refused.

**username** `string` *required*

The WordPress account the application password belongs to.

**application\_password** `string` *required*

An application password. Paste it as WordPress shows it: the spaces are ignored.

**okta**

The IT service desk AI employee's identity provider (Beta); no knowledge source reads through it.

**site\_url** `string` *required*

Your Okta org: `your-company`, `your-company.okta.com`, or any address on it, including the
`-admin` console's. It must be exactly one name under `okta.com`, `oktapreview.com` or
`okta-emea.com`; a custom domain is refused. **It is fixed for the life of the connection**.

**token** `string` *required*

An Okta API token. It acts with the permissions of the administrator who created it.

**google\_workspace**

The IT service desk AI employee's identity provider (Beta).

**service\_account\_json** `string` *required*

The whole JSON key file of a service account with domain-wide delegation. Only its
`client_email` and `private_key` are kept; every other field, `token_uri` among them, is
dropped. At most 4,096 characters.

**admin\_email** `string` *required*

The Google Workspace administrator the service account acts as.

**microsoft\_entra**

The IT service desk AI employee's identity provider (Beta).

**tenant\_id** `string` *required*

The directory (tenant) id, a GUID.

**client\_id** `string` *required*

The app registration's application (client) id, a GUID.

**client\_secret** `string` *required*

A client secret's value, not its id.

**gmail**

The Sales AI employee's mailbox (Beta). A service account for mail, apart from the IT service
desk's, with domain-wide delegation of `gmail.compose` and `gmail.readonly`.

**service\_account\_json** `string` *required*

The whole JSON key file. Only its `client_email` and `private_key` are kept. It names no
administrator: the mailbox is the one the Sales Email tool is attached with.

**microsoft\_outlook**

The Sales AI employee's mailbox (Beta). An app registration for mail, apart from the IT service
desk's, with the Graph application permission `Mail.ReadWrite` (and `Mail.Send` to send).

**tenant\_id** `string` *required*

The directory (tenant) id, a GUID.

**client\_id** `string` *required*

The app registration's application (client) id, a GUID.

**client\_secret** `string` *required*

A client secret's value, not its id.

## Response

Returns `201` with the connection, as [Get a connection](https://docs.mithunai.com/api-reference/connections/get-connection.md) describes it.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/connections" \
  --header "Authorization: Bearer $MITHUNAI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Docs team Confluence",
    "kind": "atlassian",
    "fields": {
      "site_url": "https://your-company.atlassian.net",
      "email": "docs-bot@example.com",
      "api_token": "'"$ATLASSIAN_API_TOKEN"'"
    }
  }'
```

```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "6f1c2b9a-4d3e-4a8b-9c7d-2e1f0a9b8c7d",
  "name": "Docs team Confluence",
  "kind": "atlassian",
  "host": "your-company.atlassian.net",
  "source_count": 0,
  "created_at": "2026-10-13T09:00:00+00:00",
  "updated_at": "2026-10-13T09:00:00+00:00",
  "rotated_at": null,
  "last_used_at": null
}
```

```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "validation_error",
  "message": "Enter the address of your Atlassian site, such as https://your-company.atlassian.net."
}
```

```json 409 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "code": "conflict", "message": "A connection with that name already exists." }
```

```json 503 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "dependency_failure",
  "message": "Saved connections are not available on this deployment yet."
}
```


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