> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage plugins from your app

> Install and uninstall Reason plugins and their bundled skills, choose personal or team, and run the plugin sign-in from your app with the HTTP API or the CLI.

A plugin connects Reason to another service through an MCP server or a native app connector. Use this page when your own app installs plugins, signs people in to them and removes them, instead of sending people to **Customize > Plugins** in the Reason app.

## What you will have

* A plugin installed for one person or for the whole team, with its bundled skills.
* A sign-in your app starts, follows and cancels, which sends the person back to your app.
* An uninstall that removes the connection and the skills that came with it.

## Prerequisites

Create an API key in **Settings > API** with the scopes below, and export it. Do not paste the key into a file.

```bash theme={null}
export REASON_API_KEY=reason_...
```

| Scope | Why |
| - | - |
| `mcp:read` | List plugins, read one plugin, read a sign-in |
| `mcp:write` | Install, uninstall, start and cancel a sign-in |
| `sessions:read` | Only to follow connection events on the workspace event stream |

For the CLI, you need version 0.2.753 or later. Check with `reason --version`, and update with `curl -fsSL https://reasonmachines.com/install.sh | bash`. The CLI signs in with `REASON_API_KEY` or a saved `reason login`. See [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md).

## Base URL and calls

Every call goes to `https://api.reasonmachines.com/v3/organizations/{orgId}/plugins`, with `Authorization: Bearer $REASON_API_KEY`. Get `orgId` once from `GET /v3/self` (the field is `org_id`).

| Step | Call | CLI |
| - | - | - |
| [List plugins](https://ara-90a60a07.mintlify.site/api-reference/plugins/list-plugins.md) | `GET /plugins`, query `installed`, `source`, `q`, `reason_id` | `reason plugins list` |
| [Get a plugin](https://ara-90a60a07.mintlify.site/api-reference/plugins/get-a-plugin.md) | `GET /plugins/{slug}` | `reason plugins get SLUG` |
| [Install a plugin](https://ara-90a60a07.mintlify.site/api-reference/plugins/install-a-plugin.md) | `POST /plugins/{slug}/install` | `reason plugins install SLUG` |
| [Uninstall a plugin](https://ara-90a60a07.mintlify.site/api-reference/plugins/uninstall-a-plugin.md) | `DELETE /plugins/{slug}` | `reason plugins uninstall SLUG` |
| [Start a plugin sign-in](https://ara-90a60a07.mintlify.site/api-reference/plugins/start-a-plugin-sign-in.md) | `POST /plugins/{slug}/sign-in/start` | `reason plugins start-sign-in SLUG` |
| [Get a plugin sign-in](https://ara-90a60a07.mintlify.site/api-reference/plugins/get-a-plugin-sign-in.md) | `GET /plugins/sign-in/{signInId}` | `reason plugins get-sign-in ID` |
| [Cancel a plugin sign-in](https://ara-90a60a07.mintlify.site/api-reference/plugins/cancel-a-plugin-sign-in.md) | `DELETE /plugins/sign-in/{signInId}` | `reason plugins cancel-sign-in ID` |

## What a plugin looks like

`listPlugins` and `getPlugin` return the same plugin object. The fields your app needs:

| Field | Meaning |
| - | - |
| `slug` | Stable identifier. It goes in every path. |
| `source` | `curated`, `grok`, `codex`, `cursor`, `devin`, `custom` or `native` |
| `auth_type` | `oauth` (browser sign-in), `bearer`, `api_key` or `basic` (credentials in `secrets`), `none`, or `native` |
| `secret_names` | The keys `installPlugin` accepts in `secrets`, for example `MCP_API_KEY` |
| `scope` | The scope an install uses when you send none |
| `supported_scopes` | `personal` and/or `organization` |
| `connectable`, `setup` | Whether it can be installed from the API now; if not, `setup` says what blocks it |
| `bundled_skills` | Skills shipped with the plugin: `slug`, `installed`, `installed_scopes` |
| `installed` | Whether you see at least one installation |
| `accounts` | Every installation you see (below) |

Each entry in `accounts` is one installation: `connection_id`, `adapter` (`mcp` or `native`), `scope` (`personal`, `organization` or `reason`), `account_id`, `account_name`, `connection_state` and `can_manage`. For an MCP installation, `connection_id` is also its `mcp_server_id`. A member never sees another member's personal installation.

## Personal or team

`scope` decides who the installation belongs to.

| `scope` | Installs |
| - | - |
| `personal` | One connection for the caller's own account |
| `organization` | One shared connection for the whole team |
| `reason_id` instead of `scope` | A Reason's own connection |

When you send no `scope`, the install uses the plugin's `scope`. The value must be in `supported_scopes`; anything else is a `400`.

Bundled skills install in the same scope as the plugin. Team skills belong to owners and admins: a member who installs a plugin for the organization still gets the shared connection, but each team skill reports `skill_scope_forbidden` in the response.

One person can see a personal and a team installation of the same plugin at once. Name the one you mean when you start a sign-in or uninstall.

## Install a plugin and its skills

`POST /plugins/{slug}/install`. Every field is optional.

| Field | Meaning |
| - | - |
| `scope` | `personal` or `organization`, as above |
| `reason_id` | Install it as this Reason's own connection |
| `secrets` | Credentials keyed by names from `secret_names`. Write-only: never returned. |
| `install_skills` | Install the bundled skills. Default `true`. |
| `skill_slugs` | Install only these bundled skills. An unknown slug is a `400` that names the valid ones. |
| `start_sign_in` | For an OAuth or native plugin, start the sign-in now (see below) |
| `return_url` | Where the browser goes when that sign-in ends |
| `idempotency_key` | With `start_sign_in`, identifies that sign-in |

The response has:

* `plugin`: the plugin, now with your installation in `accounts`.
* `mcp_server_id`: the installation this call created or found. Null for a native plugin, whose connection is created by its sign-in.
* `already_installed`: `true` when it was already installed in that scope.
* `skills`: one entry per bundled skill, with `slug`, `installed`, `skill_id` and `error`. A skill that fails reports `error` and does not fail the install.
* `oauth_needed`: present for an OAuth or native plugin that still needs a sign-in, with `sign_in` (the sign-in, when you sent `start_sign_in`) and `error` (why it could not start; an MCP plugin stays installed). A native plugin (`source: native`, such as Slack) has nothing installed until its sign-in succeeds, so when its sign-in cannot start, `installPlugin` answers with the HTTP error itself and no `oauth_needed`.

Installing is safe to retry. Installing again in the same scope returns `already_installed: true` with the same `mcp_server_id`, and still installs requested skills and starts a requested sign-in. Sending new `secrets` for an existing installation is a `409` `mcp_server_already_installed`: change its credentials with [Update an MCP server](https://ara-90a60a07.mintlify.site/api-reference/mcp-servers/update-an-mcp-server.md) instead.

A plugin with `connectable: false` answers `422` `plugin_not_connectable`; read its `setup`.

## Sign in from your app

OAuth and native plugins need the person to approve access at the provider. Your app starts the sign-in, opens the provider's page, and waits for the result.

### 1. Start it

Either install with `start_sign_in: true` and read `oauth_needed.sign_in`, or call `POST /plugins/{slug}/sign-in/start` for a plugin that is already installed. A catalog plugin that is not installed answers `422` `plugin_not_installed`.

| Field | Meaning |
| - | - |
| `mcp_server_id` | The installation to sign in, from `accounts` |
| `connection_id` | A native connector's existing connection, to reconnect it |
| `scope`, `reason_id` | Pick the installation when there are several. Default: your personal installation, else the team's. |
| `return_url` | Where the browser goes when the sign-in ends |
| `oauth_client` | `{ client_id, client_secret }`, only for a custom HTTP MCP server whose authorization server has no dynamic client registration |
| `idempotency_key` | Identifies this sign-in for retries |

Both return a sign-in: `sign_in_id`, `status` (`pending`), `authorize_url`, `expires_at`, `plugin_slug`, `mcp_server_id` and `return_url`.

Use a new `idempotency_key` for each sign-in. A retry with the same key for the same installation returns the same sign-in instead of starting another. A key that already started a sign-in for a different installation is refused with `409` `idempotency_key_reused`.

### 2. Open the provider's page

Open `authorize_url` in the person's browser. It is the provider's consent page. The sign-in expires 15 minutes after it starts (`expires_at`).

### 3. Come back to your app

When the sign-in ends, Reason sends the browser to `return_url`. It accepts:

* `https://` URLs
* `http://localhost` and `http://127.0.0.1`
* an app scheme, such as `myapp://callback`

Up to 2,048 characters. Reason rejects with `400`: `javascript:`, `data:`, `vbscript:`, `file:`, `blob:` and `about:` URLs, protocol-relative and scheme-less URLs, backslashes, whitespace and control characters, and credentials in the URL.

On the redirect Reason adds only `sign_in_id`, `status`, `connection_id` and `error`, never tokens or codes. Query parameters already in `return_url` are kept, so you can carry your own state:

```text theme={null}
https://app.example.com/plugins/done?tab=linear&sign_in_id=...&status=succeeded&connection_id=...
```

Treat the redirect as a hint that the sign-in ended. Anyone can open that URL, so confirm the result with `getPluginSignIn` before you show the plugin as connected.

### 4. Read the result

Poll `GET /plugins/sign-in/{signInId}` until `status` is no longer `pending`. The member who started a sign-in can read it, and so can owners and admins.

| `status` | Meaning |
| - | - |
| `pending` | The person has not finished at the provider |
| `succeeded` | Connected: `connection_id`, `account_id`, `account_name` |
| `failed` | `error_code` and `error_message` say why |
| `cancelled` | Your app cancelled it |
| `expired` | 15 minutes passed without an answer |

### 5. Cancel it

If the person closes your dialog or gives up, send `DELETE /plugins/sign-in/{signInId}`. Cancelling deletes the one-time OAuth state, so a browser that finishes consent afterwards saves nothing and is sent to `return_url` with `status=cancelled`. A browser that finishes after the sign-in expired is sent there with `status=expired`. For a native connector, a browser that comes back after the sign-in expired, or that was denied at the provider after a cancel, lands on Reason's own page instead of `return_url`, so always confirm the outcome with `getPluginSignIn`.

Cancelling is idempotent: a finished, expired or already-cancelled sign-in comes back unchanged. It never removes an existing connection.

## Uninstall a plugin

`DELETE /plugins/{slug}` removes one installation. Name it with a query parameter:

| Query | Meaning |
| - | - |
| `mcp_server_id` | The MCP installation, from `accounts` |
| `connection_id` | The native connector's connection, from `accounts` |
| `scope` | `personal`, `organization`, or `reason` with `reason_id` |
| `keep_skills=true` | Keep the bundled skills installed |

With exactly one installation you can manage, you need none of them. With several and none named, the call answers `409` `plugin_installation_ambiguous` and lists them. You can manage an installation when its `can_manage` is `true`: owners and admins can, and so can the member who installed a personal one.

Uninstalling revokes the OAuth grant at the provider where the provider supports it. It removes the plugin's bundled skills in that scope, unless you send `keep_skills=true` or another installation there still uses them. The response lists `removed` installations and `removed_skills`.

Uninstalling is safe to retry. Treat `404` `plugin_not_installed` (`plugin_not_found` for a custom server) as done: the installation is gone, whether your earlier call or another uninstall removed it. A `502` `plugin_uninstall_failed` means a native connection could not be removed; try again.

## Follow changes

Installs, sign-ins and uninstalls from any surface, the Reason app included, arrive on [Stream workspace events](https://ara-90a60a07.mintlify.site/api-reference/workspace-events/stream-workspace-events.md) as `connection.created`, `connection.updated` and `connection.removed`. On that stream they need `mcp:read` as well as `sessions:read`, and a personal connection's events reach only its owner. Use them to refresh your plugin list instead of polling it.

## Worked example with curl

This installs Linear for yourself, signs in, and removes it again. It uses `jq`.

```bash theme={null}
API=https://api.reasonmachines.com/v3
AUTH="Authorization: Bearer $REASON_API_KEY"
ORG_ID=$(curl -sS -H "$AUTH" "$API/self" | jq -r .org_id)
PLUGINS="$API/organizations/$ORG_ID/plugins"
```

**1. List.** Find the plugin, its scopes and its skills.

```bash theme={null}
curl -sS -H "$AUTH" "$PLUGINS?q=linear" \
  | jq '.items[] | {slug, auth_type, scope, supported_scopes, installed, skills: [.bundled_skills[].slug]}'
```

**2. Install for yourself.**

```bash theme={null}
curl -sS -H "$AUTH" -H "content-type: application/json" -X POST "$PLUGINS/linear/install" \
  -d '{"scope": "personal"}' | tee install.json \
  | jq '{mcp_server_id, already_installed, skills, oauth_needed}'
MCP_SERVER_ID=$(jq -r .mcp_server_id install.json)
```

**3. Start the sign-in** with a return link and a new idempotency key.

```bash theme={null}
BODY=$(jq -n --arg id "$MCP_SERVER_ID" --arg key "linear-$(date +%s)" '{
  mcp_server_id: $id,
  return_url: "https://app.example.com/plugins/done",
  idempotency_key: $key
}')
curl -sS -H "$AUTH" -H "content-type: application/json" -X POST "$PLUGINS/linear/sign-in/start" \
  -d "$BODY" | tee sign-in.json | jq '{sign_in_id, status, authorize_url, expires_at}'
SIGN_IN_ID=$(jq -r .sign_in_id sign-in.json)
```

Open `authorize_url` in your browser and approve access.

**4. Poll** until it is no longer pending.

```bash theme={null}
while [ "$(curl -sS -H "$AUTH" "$PLUGINS/sign-in/$SIGN_IN_ID" | tee sign-in.json | jq -r .status)" = pending ]; do
  sleep 3
done
jq '{status, connection_id, account_name, error_code, error_message}' sign-in.json
```

**5. Cancel** when the person gives up. On a sign-in that already finished, this returns it unchanged.

```bash theme={null}
curl -sS -H "$AUTH" -X DELETE "$PLUGINS/sign-in/$SIGN_IN_ID" | jq '{sign_in_id, status}'
```

**6. Uninstall** your personal installation and its skills.

```bash theme={null}
curl -sS -H "$AUTH" -X DELETE "$PLUGINS/linear?scope=personal" | jq '{removed, removed_skills}'
```

## The same example with the CLI

The CLI finds your organization itself. Path parameters go on the command line; `query` and `body` go in JSON through `--input-file FILE`, or `--input-file -` for stdin. Each command prints one JSON object with the API response in `data`.

```bash theme={null}
# 1. List
echo '{"query":{"q":"linear"}}' | reason plugins list --input-file - \
  | jq '.data.items[] | {slug, auth_type, supported_scopes, installed}'

# 2. Install for yourself
echo '{"body":{"scope":"personal"}}' | reason plugins install linear --input-file - \
  | jq '.data | {mcp_server_id, already_installed, skills}'

# 3. Start the sign-in, then open authorize_url in your browser
jq -n --arg key "linear-$(date +%s)" \
  '{body: {scope: "personal", return_url: "https://app.example.com/plugins/done", idempotency_key: $key}}' \
  | reason plugins start-sign-in linear --input-file - \
  | jq '.data | {sign_in_id, authorize_url, expires_at}'

# 4. Poll
reason plugins get-sign-in SIGN_IN_ID | jq '.data | {status, account_name, error_code}'

# 5. Cancel
reason plugins cancel-sign-in SIGN_IN_ID | jq '.data.status'

# 6. Uninstall
echo '{"query":{"scope":"personal"}}' | reason plugins uninstall linear --input-file - \
  | jq '.data | {removed, removed_skills}'
```

To install and start the sign-in in one call:

```bash theme={null}
echo '{"body":{"scope":"personal","start_sign_in":true,"return_url":"https://app.example.com/plugins/done"}}' \
  | reason plugins install linear --input-file - \
  | jq '.data.oauth_needed'
```

`reason tools describe installPlugin` prints the exact fields of any operation. Pass `--workspace SLUG|ID` to use another signed-in Workspace.

On an HTTP error the CLI prints an error class and the status, such as `{"ok":false,"error":{"code":"conflict","status":409,...}}`, not the API's error code. Call the API directly when your app needs to tell `plugin_installation_ambiguous` from `mcp_server_already_installed`.

## Errors

| Status | `error` | What to do |
| - | - | - |
| `400` | (invalid input) | Unsupported `scope`, unknown skill slug (the message names valid ones), invalid `return_url`, or unexpected `secrets` |
| `409` | `mcp_server_already_installed` | Change credentials with [Update an MCP server](https://ara-90a60a07.mintlify.site/api-reference/mcp-servers/update-an-mcp-server.md) |
| `409` | `plugin_installation_ambiguous` | Pass `mcp_server_id`, `connection_id` or `scope` |
| `409` | `idempotency_key_reused` | Use a new key for each sign-in |
| `422` | `plugin_not_connectable` | Read the plugin's `setup` |
| `422` | `plugin_not_installed` | Install first, or install with `start_sign_in` |
| `404` | `plugin_not_installed`, `plugin_not_found` | On uninstall: already gone, treat as done |
| `502` | `plugin_uninstall_failed` | A native connection was not removed; retry |

## Check it works

* After step 2, `GET /plugins/linear` lists your installation in `accounts` with `scope: "personal"`, and each bundled skill shows `personal` in `installed_scopes`.
* After step 4, `status` is `succeeded`, and `account_name` names the account you approved.
* After step 6, the plugin's `installed` is `false` (unless you also see a team installation), and a second uninstall answers `404` `plugin_not_installed`.

## Next

* [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md)
* [Connect an agent over MCP](https://ara-90a60a07.mintlify.site/docs/mcp.md)
* [Plugins API reference](https://ara-90a60a07.mintlify.site/api-reference/plugins/list-plugins.md)


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