Appearance
Integrations
Integrations connect an ioLoop Project to external services, APIs, and tools. A configured Connection makes the selected service available to supported Pages, Page Flow, Cloud Flow, Widgets, custom code, and AI Agent features.
Profiles and Connections keep authentication and service configuration in the Project instead of scattering credentials and endpoint details through application logic. The exact capabilities depend on the selected service. Some Connections expose commands, some provide server-only methods or authenticated SDK objects, and some are intended for a particular Widget or AI Agent workflow.
For the complete creation and management workflow, see Connections. For service-specific requirements, see Connection Services.
How Integrations Fit Into a Project
An integration normally involves four layers:
| Layer | Purpose |
|---|---|
| External service | The provider account, API, MCP server, or other system used by the Project. |
| Profile | Stores authentication and authorization information for a service. A Profile can be reused by compatible Connections. |
| Connection | Gives the configured service a unique Project name and stores any Connection-specific settings. |
| Project logic | Uses the Connection from Page Flow, Cloud Flow, a Widget, custom code, or a supported AI Agent capability. |
For example, a SendGrid Profile stores the API key, while a SendGrid Connection selects that Profile and defines the sender address. Project logic then selects the named Connection when sending email.
The distinction matters when a Project has multiple accounts or environments. A Project can create separate Profiles and Connections for test and production accounts, different business units, or different provider configurations.
Where Connections Can Be Used
Connection capabilities are service-specific and context-specific.
| Context | Supported Uses |
|---|---|
| Page Flow | Invoke commands explicitly supported for the client context or use a Widget that works with a configured Connection. The operation itself is performed by the server. |
| Client API | Call a client-supported Connection command through $io.system.connectionCommand(...). |
| Cloud Flow | Invoke supported commands, call Connection methods, use provider-specific Server APIs, or obtain authenticated SDK objects where supported. |
| Widgets | Use purpose-built integration behavior, such as supported payment operations. |
| AI Agents | Make supported Connections available as tools or MCP-backed capabilities where the service supports that integration mode. |
A Connection appearing in the Project does not mean every interface above is available. Use the relevant service guide and Programming Guide reference to determine which operations are supported.
Commands and Server Methods
Commands and methods are separate Connection interfaces.
Connection Commands
A Connection command is an operation explicitly exposed by a Connection service. Not every Connection provides commands.
Commands can be supported in one or both execution contexts:
- Client context: The command can be initiated by Page Flow or the Client API. The request is sent to the server, which executes the command using the configured Connection.
- Server context: The command can be initiated by Cloud Flow or the Server API.
Use the Execute Connection Command (connectioncommandcall) block or $io.system.connectionCommand(...) only with commands documented for the current context. The editor's command selector filters available commands according to the selected Connection and Page Flow or Cloud Flow context.
For block and API signatures, see Page Flow Connection Blocks, Cloud Flow Connection Blocks, and $io.system.
Connection Methods
Connection methods are server-only. They are available through the Connection Function Call (connectionfunctioncall) Cloud Flow block and, when dynamic selection is required, $io.system.connectionMethod(...).
When writing custom Cloud Flow JavaScript and the service is known, use the documented service-specific Server API directly, such as $io.google, $io.stripe, or $io.twilio. The generic connectionMethod API primarily provides the calling convention used by the Cloud Flow block.
Methods cannot be called from Page Flow or the Client API.
Profiles and Connections
Profiles and Connections solve different configuration problems.
Profiles
A Profile stores service authentication such as:
- API keys or secrets.
- OAuth authorization and scopes.
- Account identifiers and access tokens.
- Provider environment or currency settings when those settings belong to authentication.
The available fields depend on the service. OAuth-based Profiles may open the provider's authorization flow after their settings are saved.
Profiles are shared by the development and published versions of the Project. A credential or authorization change can therefore affect both versions and every Connection that uses the Profile.
Connections
A Connection:
- Selects a service and one of its Profiles.
- Has a unique alphanumeric name within the Project.
- Stores settings specific to that use of the service.
- Defines applicable Access (Security) policies.
- Becomes selectable from supported blocks, APIs, Widgets, and AI Agent configuration.
Several Connections can reuse one Profile. For example, two API Call Connections can use the same authentication Profile while targeting different URLs and HTTP methods.
Deleting a Connection does not delete its Profile. A Profile can be deleted only when no development or published Connection refers to it. If a deleted development Connection still exists in the published Project, republish the Project to remove the published Connection before deleting its now-unused Profile. See Deleting a Profile for the complete workflow.
Supported Connection Services
ioLoop currently provides Connections for the following service categories:
| Category | Services |
|---|---|
| General APIs and credentials | API Call, API Key |
| AI and tools | OpenAI, MCP Server |
| Google services | |
| Messaging and communication | SendGrid, Twilio, Slack |
| CRM and marketing | HubSpot, Mailchimp, Constant Contact |
| Payments | Stripe, Square |
Security Model
Profiles frequently contain credentials that must not be placed in frontend code.
Follow these principles:
- Store supported credentials in the Profile rather than hardcoding them in Page or Cloud Flow code.
- Use Cloud Flow for trusted validation, authorization, and business rules.
- Grant only the provider scopes and Project User Groups required by the operation.
- Do not assume that restricting a Page also protects a Connection command called from another path.
- Treat API responses as untrusted input and validate the data used by the Project.
- Do not include secrets in logs, errors, Page content, or values returned to the browser.
The Access (Security) action controls which Project User Groups can perform the operations exposed for that Connection. Operation labels vary by service. For details, see Connection Access.
For the available group identities and role levels, see User Groups. To create Project Users and assign their group membership, see Users.
Development, Testing, and External Effects
Project Preview and Cloud Flow testing do not automatically create a sandbox for an external provider. A test can send a real email or message, change CRM data, create a payment operation, modify a Google file, or call a production API.
Before testing:
- Confirm which provider account and environment the Profile uses.
- Prefer test, sandbox, or restricted credentials where the provider supports them.
- Confirm the selected Connection name and provider scopes.
- Use controlled test recipients and records.
- Test failure handling as well as successful operations.
- Review external provider logs or dashboards when applicable.
Connection changes made in the Project Editor affect the development version first. Republish the Project when a new, edited, cloned, deleted, or access-modified Connection must be reflected in the published application.
Integration Workflow
A reliable integration workflow is:
- Prepare the external provider account and required credentials or OAuth application.
- Open Integrations → Connections.
- Create a Profile for the service, or select an existing compatible Profile.
- Create and name the Connection.
- Configure any Connection-specific settings.
- Review Access (Security) for operations that can be initiated from the application.
- Select the Connection from the supported Page Flow, Cloud Flow, Widget, custom-code, or AI Agent interface.
- Test with controlled input and verify the external result.
- Publish the Project and verify the published invocation path.