Install a Plugin

Use this guide when Navigic has enabled a reviewed first-party or approved plugin for your workspace. Plugin installation is currently a managed-preview path: public self-serve marketplace discovery and third-party installation are not generally available yet.

What Installation Means

A plugin lets an agent call an external service through a reviewed operation contract. Installation does not load arbitrary code into Navigic. A plugin installation records the provider connection, approved scopes, allowed operations, channel binding when needed, and audit metadata used when an agent calls the plugin.

Before You Start

You need:

A Navigic workspace with plugin access enabled.
Workspace admin access in Navigic.
Admin or installer permission in the external provider, such as Slack.
A published agent revision if the plugin will be bound to a channel.
A clear decision about which operations should be read-only, write-capable, or disabled.

Do not paste access tokens, refresh tokens, signing secrets, client secrets, or provider verification tokens into chat, issue trackers, public docs, or browser storage. If a secret was shared in an unsafe place, rotate it in the provider console before continuing.

1. Open the Enabled Install Flow

Open the dashboard and use the plugin install flow enabled for your workspace. In managed preview, this may be a Navigic-provided install link or a workspace setup surface for a specific provider.

If you do not see a plugin or Slack setup entry, your workspace is not enabled for self-serve installation. Email hello@navigic.ai with your account email, workspace name, provider, and the plugin you want to install.

2. Review the Plugin

Before connecting the provider account, review:

Plugin name, publisher, and version.
Publisher verification status, license, documentation, support, privacy, terms, changelog, and release status.
Provider account or workspace being connected.
Requested OAuth scopes or API permissions.
Agent operations the plugin exposes.
Which operations can read data, write data, or send external messages.
Whether write operations require human approval.
What data the plugin processes, what may become model-visible, what is stored, and what is sent back to the provider.
Where provider events or channel messages will appear in Navigic.

Prefer the smallest useful permission set. Enable read operations before write operations, and grant write or external-send operations only when the agent needs them for a specific support workflow.

For each provider, keep a scope review table like this in your internal rollout notes:

Scope	Access	Enables	Required?
`provider.read`	Read provider records	Search or validate state	Yes
`provider.write`	Write provider records	Create or update records	Optional
`provider.send`	Send external messages	Reply in the provider	Optional

If an optional scope is not approved, leave the related operation disabled and reconnect only when that feature is actually needed.

3. Approve or Add the Provider Connection

Continue through the provider OAuth flow, provider install screen, or managed-preview API-key setup step. Confirm that the provider workspace or account shown in the setup flow is the one you intend to connect.

For OAuth-based plugins, the provider redirects back to Navigic or the managed plugin service after approval. If the redirect fails, restart the install flow instead of refreshing or reusing the old callback URL.

For API-key based plugins, paste keys only into the enabled dashboard setup surface. Do not paste provider API keys into chat, support messages, tickets, or agent prompts.

4. Bind the Plugin to an Agent or Channel

After the provider connection succeeds, choose where the plugin is allowed to run:

Agent-bound plugins expose selected operations to a published agent revision.
Channel-bound plugins receive or send messages for a concrete channel, such as Slack.
Some plugins need both an agent operation grant and a channel binding.

For channel-bound setup, pick a published agent revision that should serve that channel. Draft changes are not live until you publish a new revision and bind the channel to it.

5. Verify the First Action

Run one low-risk test:

Confirm the install page shows the provider connection as active.
Confirm the intended agent or channel binding is selected.
Send a test request that exercises the narrow operation you enabled.
Review channel activity or runtime evidence for the request, served agent, provider result, and error status.
Confirm no hidden prompts, credentials, raw provider tokens, or private workspace data appear in the user-facing answer.

If the plugin sends messages to another system, test in a low-risk channel before using it with customers.

Reconnect or Revoke Access

Use the provider console and the Navigic install surface for lifecycle changes:

Reconnect when OAuth consent expired, API-key credentials changed, scopes or permissions changed, or the provider account changed.
Revoke or uninstall when the plugin is no longer needed.
Rotate provider secrets if a token, client secret, signing secret, or verification token was exposed.
Review any agent operation grants after reconnecting, because a provider reconnect does not automatically mean every agent should use the plugin.

Provider behavior differs: uninstalling an app, revoking an OAuth grant, and removing an agent operation grant are separate actions in some systems.

Slack Managed-Preview Path

Slack is the first-party reference plugin and a managed-preview channel path. When Slack setup is enabled for your workspace:

Start from the Slack setup flow or Navigic-provided install link.
Approve Slack OAuth in the correct Slack workspace.
Review requested scopes such as app_mentions:read, chat:write, commands, channels:read, and groups:read.
Choose the Slack channel ID or channel selected by the setup flow.
Confirm the bot is a member of that Slack channel.
Bind the Slack channel to a published Navigic agent revision.
Choose the reply mode, such as threaded replies, if the setup flow exposes that option.
Send an app mention or slash-command test and review Navigic channel activity.

Common Slack scopes:

Scope	Access	Enables
`app_mentions:read`	Read app mentions	Receive channel mentions.
`chat:write`	Send messages	Reply in Slack.
`commands`	Receive slash commands	Route slash-command requests.
`channels:read`	Read public channel metadata	Validate public channels.
`groups:read`	Read private channel metadata	Validate private channels where approved.

If Slack setup is not visible in the dashboard, treat Slack as contact-led for that workspace and email hello@navigic.ai.

Troubleshooting

I cannot see the plugin install page. The workspace may not have plugin access enabled, or self-serve install may not be generally available for that plugin. Email hello@navigic.ai with the account email, workspace name, provider, and plugin name.

OAuth failed or returned to the wrong page. Restart the install flow from Navigic. OAuth callbacks are short-lived and should not be reused. Provider redirect URIs must match the environment being installed.

Slack says the bot cannot access the channel. Confirm the bot is installed in the correct Slack workspace, the channel ID is correct, the channel is not archived, and the bot has joined the channel.

The plugin is installed but the agent cannot use it. Confirm the agent has the specific plugin operation grant, the operation is allowed by policy, and the channel or agent is serving the published revision that includes the grant.

A write action did not run. Write and external-send operations may require human approval, an idempotency key, and valid provider scopes. Review the approval and activity records before retrying.

The support agent cannot install the plugin for me. The support agent can explain setup steps and point to docs. It cannot inspect private workspace state, approve OAuth consent, save API keys, install provider apps, rotate secrets, or change agent permissions.