Integrations
Adding an integration provider
The integration catalog is data, not code. Adding a new connectable service is a configuration task: you add one row to the integration-providers global collection. There is no code to write and no deploy required — once the row exists, the provider appears in Marketplace → Integrations for accounts to install, and is manageable under Settings → Integrations like any other provider.
This is a platform-admin task.
What a provider row contains
Each row is a self-contained "pre-connection" — everything an account needs to connect the service:
| Field | What to put | Example |
|---|---|---|
| key | Stable, lowercase identifier used by the system to resolve the credential. Do not change it after launch. | mailchimp |
| name | Human-readable provider name shown in the catalog. | Mailchimp |
| category | Grouping in the catalog (e.g. AI, Payments, Email, Messaging, Calendar, Advertising). | Email |
| logo | The provider's logo, shown in the Marketplace and Settings. | (uploaded image) |
| description | A short line describing what the provider does. | Email marketing and audiences. |
| auth type | How the provider authenticates (e.g. API key). | API key |
| credential label / hint | The label and hint for the paste field in the connect dialog. | API Key / Starts with a key id |
| help URL + instructions | The link and wording for "where to find your key", shown in the connect dialog. | https://... |
Steps
- Open the
integration-providersglobal collection as a platform admin. - Add a row and fill in the fields above. Choose a clear, stable
key— this is the identity the system uses to resolve the credential for the account. - Upload the logo and write a concise description and category so it reads well in the catalog.
- Set the credential label/hint and the help URL + instructions so users know exactly where to find their key and what to paste.
- Save. The provider is now live in Marketplace → Integrations.
What happens next
Once the row exists, the provider follows the standard Integrations & BYOK flow with no further work:
- Accounts browse it in Marketplace → Integrations.
- Install / Connect opens the connect dialog using your credential label, hint, and help link.
- Pasting the key saves and tests it; "I'll add it later" creates a disconnected row.
- The key is then managed under Settings → Integrations (masked field, Save, Test).
If the provider supplies a credential the AI consumes, getAiConfig resolves the tenant's key by the key you chose — so pick it carefully and keep it stable.