Using Connections

Connections let Cloud Flow use configured external services from trusted server-side workflows. Use them when a Project needs to send a message, call an external API, work with a payment or AI provider, update another system, or perform an integration operation without exposing protected credentials in browser-side code.

A Connection combines a service, an authentication Profile, and settings for one named use of the service. Cloud Flow defines when to use the Connection, what operation to perform, which data to send, and how to handle the response.

This guide focuses on using Connections from Cloud Flow. For creating and managing Connections, see Integrations and Connections. For exact block inputs and API signatures, use the Cloud Flow Connections Blocks and Server API references.

When to Use Connections

Use a Connection when backend logic needs to interact with a supported external service, particularly when the operation involves:

• API keys, OAuth credentials, or other protected service configuration.
• Creating or changing data in an external system.
• Combining Project Database records with an external service operation.
• Sending notifications, making payment-related requests, or invoking AI services.
• A Web Hook, Background Task, or AI Agent workflow that uses an external provider.
• Returning a controlled result to the frontend instead of exposing the provider's complete response.

Examples include sending an email when a support request is submitted, updating a CRM after a customer change, retrieving external data for processing, or initiating a payment-related action after the server validates an order.

Not every integration requires custom JavaScript. Start with the available Cloud Flow blocks or ioLoop Server APIs, then use a supported SDK when the operation requires additional provider functionality.

How Connections Fit Into Cloud Flow

Component	Responsibility
Profile	Holds credentials, OAuth authorization, provider scopes, or other authentication information. A Profile can be shared by multiple Connections.
Connection	Selects a service and Profile, has a unique Project name, and holds settings for that use of the service.
Cloud Flow	Coordinates the backend operation, validates inputs, and processes the result.
Connection blocks	Provide visual interfaces for invoking supported methods and commands on a Connection.
ioLoop Server APIs	Allow custom code to invoke supported Connection methods, commands, and integration-specific operations.
Curated SDK libraries	Provide additional supported provider functionality in server-side JavaScript.
Page Flow or custom frontend code	Starts the user-facing interaction and handles the result returned by Cloud Flow when applicable.

For example, a Page can collect a contact request and call a Cloud Flow Web Hook. The Web Hook validates the request, uses an email Connection to send a notification, and returns a result that the Page can display.

The frontend does not need the service credentials. It communicates with the trusted Cloud Flow operation instead.

Preparing a Connection-Based Workflow

Before implementing the workflow:

1. Configure the external service under Integrations → Connections.
2. Confirm that its Profile uses the intended provider account, environment, credentials, and scopes.
3. Open the relevant Connection service guide and identify the supported method, command, Server API, or SDK operation.
4. Record the service identifier when custom code uses a generic Connection API.
5. Determine which Project or caller data the operation requires.
6. Decide which authorization and business rules Cloud Flow must enforce.
7. Define what a successful operation returns and what should happen if it fails.
8. Select the Connection in the appropriate Cloud Flow block or reference it from server-side JavaScript.
9. Save and test the Cloud Flow through its intended invocation path.

Use meaningful Connection names. A Project may have multiple Connections for the same service, such as different accounts or test and live environments. Confirm the selected Connection before an operation that can change external data.

Ways to Use a Connection

Cloud Flow supports several approaches. They can be combined in the same workflow.

Approach	Use It When
Connection Function Call block	You want to invoke a supported Connection method using visual blocks.
Execute Connection Command block	You want to execute a server-supported Connection command and handle success or failure with visual blocks.
$io.system.connectionMethod(...)	Service or method selection is dynamic in custom server-side JavaScript.
$io.system.connectionCommand(...)	You need a supported service command exposed through the Connection command interface.
Integration-specific $io Server API	ioLoop exposes a dedicated function for the provider operation.
Connection-backed SDK object	You need supported advanced provider functionality through an authenticated SDK object.
Curated SDK via require(...)	You need an allowed SDK library in custom code, with an appropriate supported credential source.

Choose the clearest interface that supports the required operation. These approaches differ in available methods and calling conventions; do not assume one interface accepts another interface's parameter structure.

Using Connection Blocks

Cloud Flow provides separate block interfaces for Connection methods and Connection commands.

Block	Block Name	Role
Connection	connectionasstring	Selects a configured Connection.
Connection Method	connectionfunctionasstring	Selects a supported server-side method.
Connection Function Call	connectionfunctioncall	Calls the selected method with a named-parameter object and returns a Promise.
Connection Command	connectioncommandasstring	Selects a command supported in the Cloud Flow context.
Execute Connection Command	connectioncommandcall	Executes the command and provides success and failure branches.

The Connection selector carries the service and Connection information required by these blocks. You do not enter a separate service identifier when using the block interface.

Configuring a Connection Function Call

A typical workflow is:

1. Open the relevant Cloud Flow module and select Edit Flow.
2. Find the Connection-related blocks in the toolbox.
3. Add Connection Function Call to the intended operation.
4. Supply the configured Connection using a Connection block.
5. Supply the supported method using a Connection Method block.
6. Supply the method parameters as an object with the required property names and values.
7. Handle the returned Promise using the supported Promise blocks or appropriate asynchronous flow logic.
8. Inspect the operation result and continue through the correct success or failure path.
9. Save the Cloud Flow and test it with the configured Connection.

The block's Connection and Method selectors support lookup of available values in the current context. Use those lookups and the relevant method documentation rather than guessing method names or parameter properties.

Connection Function Call returns a Promise. The next operation must not assume the external call has completed merely because the request was started. Handle completion or failure before sending a success response or changing dependent records.

For exact block inputs, see Connection Function Call.

Configuring an Execute Connection Command Block

Not every Connection service exposes commands. When a service provides a command supported in the server context:

1. Add Execute Connection Command to the workflow.
2. Supply the configured Connection with a Connection block.
3. Supply the command with a Connection Command block.
4. Provide the documented command data object.
5. Handle the Connection Data in the success branch and the Connection Error in the failure branch.

Commands and methods are separate interfaces. The command selector shows commands supported for Cloud Flow; it does not list the service's Connection methods.

Calling Connections from Custom Code

The ioLoop Server API provides general-purpose functions for invoking supported Connection operations.

Connection Methods

$io.system.connectionMethod(...) is the custom-code counterpart to the Connection Function Call block. It is useful when the service, Connection, or method is selected dynamically.

const result = await $io.system.connectionMethod(
  serviceIdentifier,
  connectionName,
  methodName,
  methodParams
);

if (result.status) {
  // Continue using the successful response in result.data.
} else {
  // Handle result.err and return appropriate failure feedback.
}

serviceIdentifier must be the exact Connection service identifier documented in the service directory, such as google, stripe, or constantcontact. It is not the provider's display name. connectionName is the alphanumeric name assigned under Integrations → Connections.

For a known service in custom code, prefer its documented service-specific API, such as $io.google, $io.stripe, or $io.twilio. Use connectionMethod(...) when its generic, dynamic calling convention is required. The actual method names and parameter properties depend on the service.

The documented result includes:

Property	Meaning
status	Boolean success or failure indicator.
data	Returned data from the selected method.
err	Error information when the operation fails.

Always inspect the result rather than assuming an awaited call succeeded.

Connection Commands

The Server API also exposes:

$io.system.connectionCommand(
  serviceIdentifier,
  connectionName,
  command,
  commandParams
);

This invokes a command exposed by the Connection's service and supported in the server context. serviceIdentifier uses the same Connection service identifier documented by the service guide. Like connectionMethod, it returns a Promise with status, data, and err in the documented result.

Methods and commands are distinct supported interfaces. Use the one documented for the operation you are implementing; a method name should not automatically be treated as a command name, or vice versa.

For authoritative signatures and supported operations, see $io.system.

Integration-Specific Server APIs

For some providers, ioLoop supplies dedicated server-side APIs. These can be easier to use when they expose the required operation directly.

Examples of available API areas include:

• $io.apicall
• $io.apikey
• $io.constantContact
• $io.google
• $io.hubspot
• $io.mailChimp
• $io.sendgrid
• $io.slack
• $io.stripe
• $io.square
• $io.twilio

Use the Server API for the current provider-specific functions, supported inputs, and results. The availability of an API area does not mean every capability of the provider's public SDK is exposed through that area.

Using Authenticated SDK Objects

When the supported Connection method or integration-specific API does not provide the operation you need, Cloud Flow custom code can use curated SDK libraries and Connection-backed authentication where supported.

The Server API provides:

$io.system.sdkLibraryObjectFromConnection(serviceName, connectionName)

Here, serviceName is an SDK service name, not necessarily the Connection service identifier used by connectionCommand(...) and connectionMethod(...). The named Connection must belong to the compatible service and have a Profile that can authenticate the requested SDK object.

For example, with an appropriately configured Stripe Connection:

const stripe = $io.system.sdkLibraryObjectFromConnection(
  'stripe',
  'MyStripeConnection'
);

For a configured Google Drive Connection:

const drive = $io.system.sdkLibraryObjectFromConnection(
  'google.drive',
  'MyGoogleConnection'
);

The returned object can be used for supported SDK operations, subject to the Connection's permissions and the SDK version available in the runtime.

For example, the Google Connection service identifier is google, but Google SDK service names include google.drive, google.sheets, and google.docs. Other supported services, such as Stripe, use the same value for both identifiers.

Not every available SDK library has a corresponding Connection-backed SDK service name. Use only the SDK service names documented by the Connection service guide and Node.js Runtime and SDK Libraries. The presence of a library in the require(...) allowlist does not establish that it is supported by this helper.

Cloud Flow permits supported CommonJS-style require(...) modules from its curated allowlist. It does not provide unrestricted package installation. For the current libraries, examples, and runtime restrictions, see Node.js Runtime and SDK Libraries.

Example: Sending a Notification After a Support Request

Consider a support application in which a user submits a request and the Project should notify a support team through a configured email service.

1. Configure the Project Components

• Create the request Form and any relevant Database table.
• Configure an appropriate email Connection under Integrations.
• Create a Cloud Flow Web Hook that will process the submitted request.
• Configure the Web Hook's access rules and trusted validation.

2. Process the Request in Cloud Flow

A conceptual workflow is:

Receive support request
  Validate required values
  Check caller authorization or public submission rules
  Create or update the request record where appropriate
  Invoke the configured email Connection
  Handle the Connection result
  Build the appropriate Web Hook response

The example is a workflow outline, not a literal list of Cloud Flow block names. Choose the supported Connection method or command for the configured email service.

3. Handle Success and Failure

Decide whether a notification failure should make the entire submission fail or whether the request may be saved and the notification retried separately.

For example:

• If saving the request succeeds but sending the email fails, do not assume both operations succeeded.
• Record an appropriate status or retry requirement when the application needs follow-up.
• Return a response that accurately reflects what was completed.
• Ensure repeated requests or retries do not unintentionally create duplicate support tickets or messages.

A sequence of Database and Connection calls is not automatically an atomic transaction. Design partial-failure behavior explicitly.

4. Test Through the Real Caller

Preview the Page or Form, submit a realistic request, and inspect the Cloud Flow result and logs. Verify the configured provider environment and whether a real notification was sent.

The same pattern can be adapted to CRM updates, external API requests, AI-provider operations, and other supported Connections.

Security and Authorization

Profiles centralize service credentials and Connections make them available to supported operations, but having a Connection does not automatically authorize every caller to perform every operation through it.

For sensitive workflows:

• Check who may invoke the Web Hook or other entry point.
• Validate record ownership, User Group membership, or other applicable authorization rules on the server.
• Treat all browser and external request inputs as untrusted.
• Validate the requested external action and relevant amounts, destinations, and record identifiers.
• Send only the data the provider needs.
• Return only the information the caller is allowed to receive.
• Avoid logging API keys, OAuth tokens, full credentials, or unnecessary sensitive provider responses.

Use configured Connections instead of embedding secrets in frontend HTML, CSS, JavaScript, Page Flow, or Cloud Flow code. Use supported trusted Project configuration for secrets that are not represented by a standard provider Connection.

For Web Hook security and backend authorization, see Access Security.

Asynchronous Results and Reliability

External service operations can fail, time out, return an error response, or complete successfully even when subsequent Project operations fail.

When coordinating Connections with Database or other Cloud Flow operations:

1. Await the Connection result through the documented Promise/completion mechanism.
2. Distinguish a successful request from a successful business operation.
3. Handle validation failures and external-service errors separately where useful.
4. Decide whether the operation may safely be retried.
5. Guard against duplicate side effects for payment, notification, and record-creation workflows.
6. Return a consistent result for the calling Page, Web Hook client, or AI Agent workflow.

For payment-sensitive operations, fulfillment or access changes should depend on trusted provider confirmation, not only on a frontend success indicator.

Development, Publishing, and Profiles

Connection configuration has separate development and published versions. Creating, editing, cloning, deleting, or changing Access for a Connection affects development first. Publish the Project before relying on that change in the published Cloud Flow.

Profiles are different: their authentication and authorization information is shared by the development and published versions. Replacing credentials or reauthorizing a Profile can affect both versions and every Connection that uses that Profile.

This distinction also affects deletion:

• Deleting a Connection does not delete its Profile.
• A deleted development Connection remains in the published Project until the Project is republished.
• The published Connection continues using its Profile until that publish removes or replaces the Connection.
• A Profile cannot be deleted while any development or published Connection refers to it.

For the complete management sequence, see Deleting a Connection and Deleting a Profile.

Testing Connections

Test with the same Connection and invocation pattern the Project intends to use.

Test	What to Verify
Correct Connection	The module references the intended Connection and provider account. Custom generic API calls use the documented service identifier.
Credentials and permissions	The Connection can perform the requested method or command.
Inputs	The parameter object contains the required properties and valid values.
Successful response	The workflow handles the provider result and returns the intended outcome.
Service failure	Errors are logged safely and result in appropriate retry or user feedback.
Authorization	Unauthorized callers cannot use the Connection to perform protected actions.
Repeated execution	Retries and repeated requests do not create unintended duplicate side effects.
Test versus live	The selected Connection targets the intended provider environment.
Published behavior	The latest Connection and Access changes were published, and the shared Profile is valid for published use.

Cloud Flow test mode does not automatically switch every external provider to a test environment. Confirm the selected Connection's account, credentials, sandbox/live mode, and possible side effects before testing.

Built-in Database operations used in Page Preview automatically target development data. That isolation should not be assumed for external services called through Connections.

For log inspection and runtime diagnostics, see Testing and Logs.

Troubleshooting

Symptom	What to Check
Connection not found	Connection name, exact Connection service identifier, and whether the Connection exists in the current development or published version.
Method unavailable	The selected Connection's supported methods and the method lookup/reference.
Command unavailable	Whether the service exposes commands and whether the command supports the server context.
Invalid parameters	The method or command's required parameter object and value types.
Authentication or permission failure	Provider credentials, authorization scopes, account permissions, and intended environment.
Operation appears incomplete	Whether the returned Promise has completed and the result was checked.
Unexpected provider response	The selected operation, documented return shape, and safe error inspection.
Database and external data disagree	Whether one operation succeeded while another failed, or retries caused duplicate effects.
Works in test but not live	Whether Connection and Access changes were published, plus the shared Profile, provider environment, and access rules.
SDK object unavailable	The documented SDK service name, compatible Connection service, Connection name, Profile scopes, and Connection configuration.

Start with a simple, known-safe operation and then test through the actual Page, Web Hook, Background Task, or AI Agent workflow that consumes the Connection.

Good Practices

• Prefer configured Connections. Keep credentials in managed Project configuration.
• Choose the narrowest clear interface. Use blocks or a dedicated Server API for standard operations and supported SDKs for advanced cases.
• Use documented method and command names. Do not assume the Connection exposes every provider API operation.
• Handle Promises and results. Check completion, success, and failure explicitly.
• Authorize external actions. A valid Connection does not establish that an incoming request is permitted.
• Minimize returned data. Expose only what the consuming Page or caller needs.
• Plan for partial failure. Database changes and external actions may succeed or fail independently.
• Verify test/live configuration. Development execution can still call real external services.
• Keep logging safe. Record enough to diagnose failures without exposing secrets.

Common Mistakes

Avoid these patterns:

• Hardcoding service credentials in frontend or Cloud Flow code.
• Assuming any configured Connection can execute every method or SDK feature of the provider.
• Treating a Connection Function Call's Promise as though it had already completed.
• Confusing connectionMethod with connectionCommand without checking their documented operations.
• Passing a provider display name or SDK service name where a Connection service identifier is required.
• Assuming every curated SDK package can be obtained through sdkLibraryObjectFromConnection.
• Assuming Profile changes wait for a Project publish before affecting published Connections.
• Trusting browser-supplied account IDs, email addresses, amounts, or record IDs as authorization.
• Marking a multi-step workflow as successful after only one operation succeeded.
• Logging raw provider responses that may contain confidential information.
• Assuming a Cloud Flow test run cannot affect live external services.

Connections are most useful when they let Cloud Flow perform a well-defined external operation with centrally managed credentials, validated inputs, explicit result handling, and a clear trust boundary.

Technical Reference

• Cloud Flow Connections Blocks
• $io.system Server API
• Server API
• Node.js Runtime and SDK Libraries
• Integrations
• Connections
• Connection Services and Identifiers

Related Topics

• Cloud Flow
• Access Security
• Web Hooks
• Using Database
• Testing and Logs
• Calling Cloud Flow from Pages