Installing a Plugin

Every plugin uses the same three-step install wizard: permissions consent, configuration, and confirmation. This guide explains each step in detail.

Who can install plugins

Only users with the Admin role on a subaccount can install or uninstall plugins. Operators with Manager, Dispatcher, or Mechanic roles can see the marketplace but not install.

If your subaccount is on the free plan, you can install up to two free plugins. Paid plans get unlimited installs.

Step 1 — Permissions consent

When you click Install on a plugin detail page, the wizard opens with a plain-English permission list:

Slack would like to:

• Read rides
• Read vehicles
• Read zones

Each bullet maps to one or more permission scopes in the plugin's manifest. The wizard groups related scopes into single bullets to keep the list readable.

Admin-class scopes

Some permissions are higher risk. These are shown in amber and require an explicit checkbox confirmation:

If the plugin only needs ordinary scopes (like read:rides), no amber confirmation is required.

Step 2 — Configure

The configuration form is generated automatically from the plugin's config_schema (JSON Schema). Different plugins ask for different things:

• API keys — Veriff, Persona, Captur.ai
• OAuth connection — Slack (workspace), Zapier (Zapier account)
• Webhook destination URL — for self-built plugins
• Thresholds, channels, filters — plugin-specific tuning (e.g., "post to #ops if a vehicle has < 20% battery")

OAuth flow

If the plugin uses OAuth (Slack is the most common example), you'll click Connect and be redirected to the vendor's authorization page. Approve the requested scopes, and you'll be redirected back to Levy with the connection established.

Tokens issued during OAuth are stored encrypted at rest in Supabase Vault. Levy never displays the raw token after the initial exchange.

Encrypted secrets

API keys and other sensitive fields are also stored in Supabase Vault, encrypted per row. They're decrypted only when the plugin's handler needs them to call the vendor's API.

Step 3 — Confirm

The final screen recaps:

• The plugin name and version
• The permissions you granted
• The pricing model (free, one-time, monthly, usage)
• The vendor's terms-of-service link

Click Install. If the plugin is paid:

• One-time — Stripe charges your card immediately.
• Monthly — Stripe creates a subscription. First charge is prorated to your billing cycle.
• Usage — no charge today; you'll be billed monthly based on actual usage.

You're returned to Settings → Plugins, where the new install shows as Active.

Reinstalling a plugin

If you previously uninstalled a plugin, reinstalling reuses the same install row. Your old configuration is gone (the 30-day soft-delete window has passed by the time most operators reinstall), so you'll re-enter your config from scratch. Each subaccount can have only one active install per plugin.

Common install errors

What's next

• Configuring a plugin — editing settings after install
• Plugin billing — how charges, refunds, and the 20% fee work
• Troubleshooting — webhook failures, token rotation, and more