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.
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.
Base URL and calls
Every call goes tohttps://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).
What a plugin looks like
listPlugins and getPlugin return the same plugin object. The fields your app needs:
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.
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.
The response has:
plugin: the plugin, now with your installation inaccounts.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:truewhen it was already installed in that scope.skills: one entry per bundled skill, withslug,installed,skill_idanderror. A skill that fails reportserrorand does not fail the install.oauth_needed: present for an OAuth or native plugin that still needs a sign-in, withsign_in(the sign-in, when you sentstart_sign_in) anderror(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,installPluginanswers with the HTTP error itself and nooauth_needed.
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 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 withstart_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.
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
Openauthorize_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 toreturn_url. It accepts:
https://URLshttp://localhostandhttp://127.0.0.1- an app scheme, such as
myapp://callback
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:
getPluginSignIn before you show the plugin as connected.
4. Read the result
PollGET /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.
5. Cancel it
If the person closes your dialog or gives up, sendDELETE /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:
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 asconnection.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 usesjq.
authorize_url in your browser and approve access.
4. Poll until it is no longer pending.
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.
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
Check it works
- After step 2,
GET /plugins/linearlists your installation inaccountswithscope: "personal", and each bundled skill showspersonalininstalled_scopes. - After step 4,
statusissucceeded, andaccount_namenames the account you approved. - After step 6, the plugin’s
installedisfalse(unless you also see a team installation), and a second uninstall answers404plugin_not_installed.

