Skip to main content
The activation form is what a user fills in to connect your integration. Use BaseActivationForm for the dialog chrome, submit button, and loading states.

Basic form

Props

ActivationFormProps is IntegrationComponentProps plus:
IntegrationComponentProps is { accountId, sourceId?, integrationConfig? } plus exactly one of productId or productSlug.
  • inline — pass through; without it the form mounts its own dialog, so a page that embeds it ends up with nested dialogs
  • onSuccess — call it with an ActivationResult ({ success, configData?, externalId?, errorMessage?, metadata? }) once activation succeeds. Values you want back on the client go in configData
  • onCancel — call it when the user cancels

Secret naming

Every string field you submit becomes a secret:
The field name is the secret name. Put names in a constant to avoid drift:
Use both in the form and in handlers.

OAuth variant

For an integration whose definition declares oauth, OAuthActivationForm renders a “Connect with …” button that sends the browser to the host’s connect route, then activates once the OAuth redirect returns with a live connection. Point it at the hosted routes with the helpers from @ekanos/sdk/hooks rather than spelling the paths yourself:
config also accepts successTitle, connectedBanner, connectButtonText, activateButtonText, externalIdPrefix, and autoActivateOnConnect (default true; set false when the user should review post-connect settings before activating). Pass connectPath explicitly — its default points at a per-integration route that partner integrations do not have. useOAuthConnectionStatus(accountId, { connectionKey, checkConnection, errorParam }) is the underlying hook if you build your own form. See OAuth.

Declaration

Forms are optional. Omit it and the host renders a generic one — a plain field per value it needs.

Error handling

Errors from activate.mutateAsync become the error prop:

Troubleshooting

No IntegrationActivationProvider is mounted

Submitting rejects with No IntegrationActivationProvider is mounted. The host application must bind its activation server actions (see @ekanos/sdk/hooks IntegrationActivationProvider) above any component that activates integrations. You’re rendering outside the host (Storybook, your own app). Mount IntegrationActivationProvider from @ekanos/sdk/hooks with activate and deactivate functions:

Nested dialogs

Forgot to pass inline? The form mounts its own Dialog, causing nesting. Always pass through: inline={inline}.

Next steps

  • Secrets — credential management
  • Widgets — what renders after activation