Connections

Connections are named Project resources that configure access to external services, APIs, credentials, and MCP servers. They are created and managed under Integrations → Connections in the Project Editor.

A Connection combines a service, an authentication Profile, Connection-specific settings, and applicable Access (Security) policies. Once configured, it can be selected from the Page Flow, Cloud Flow, Widget, custom-code, or AI Agent interfaces supported by that service.

For service-specific authentication and settings, see Connection Services.

Opening Connections

To open the Connections page:

1. Open the Project in the Project Editor.
2. Select Integrations.
3. Open Connections.

The default grid shows each Connection as a service tile with its Connection name. Select a tile to open its actions.

You can switch to the table view to compare:

• Connection name.
• Service.
• Profile.
• Access (Security) assignments.

Use Search to filter Connections by name. Search does not filter by provider, Profile, or permission group.

Connection Architecture

Each Connection has three main configuration layers:

Layer	What It Contains	Reuse
Service	The integration implementation, supported operations, and available configuration fields.	Selected once when the Connection is created.
Profile	Credentials, OAuth authorization, provider scopes, account details, or other authentication settings.	Can be selected by multiple compatible Connections.
Connection settings	The unique Connection name and settings for this particular use of the service.	Belong to one Connection.

For example, an API Call Profile can hold authorization headers while separate Connections define different URLs and request methods. A SendGrid Profile can hold one API key while Connections define different sender addresses.

Naming Profiles and Connections

Profile and Connection names must contain only letters and numbers. Spaces, punctuation, underscores, and hyphens are not accepted by the creation form.

Use names that identify both purpose and environment, such as:

• SupportEmailTest
• SupportEmailLive
• PrimaryStripe
• CustomerCrm
• InternalMcp

Names become selectors and identifiers in blocks and APIs. Avoid vague names such as Test, NewConnection, or Service1 when a Project will contain several Connections.

The Connection name cannot be changed after creation. Clone the Connection with a new name when a different identifier is required, then update its consumers before deleting the original.

Creating a Connection

Select New Connection to open the creation workflow.

1. Select a Service

Choose the external service or Connection type.

The service list shows the provider name, purpose, and icon. The selected service determines:

• Which Profile settings are required.
• Whether OAuth authorization is used.
• Which Connection settings appear.
• Which commands, methods, Server APIs, SDK objects, Widgets, or AI Agent capabilities are supported.
• Which Access operations can be configured.

The service cannot be changed after the Connection is created.

2. Select or Create a Profile

Choose an existing Profile for the service or create a new one.

When creating a Profile:

1. Enter a unique alphanumeric Profile Name.
2. Complete the authentication fields shown for the service.
3. Select the smallest required OAuth scopes or provider permissions.
4. Save the Profile.
5. Complete the provider authorization window when OAuth is required.
6. Return to the Connection workflow and select the completed Profile.

Profile forms vary by service. They can request API keys, account identifiers, secrets, access tokens, OAuth client information, scopes, provider environment, or currency.

A Profile can be reused. Before creating another Profile, determine whether an existing one represents the same provider account, environment, and required scopes.

Do not reuse a Profile merely because it belongs to the same service. Separate Profiles are appropriate when Connections need different accounts, environments, credentials, or authorization scopes.

OAuth Profiles

OAuth-based services can offer one or more authorization modes:

• An ioLoop-provided OAuth application.
• A custom OAuth application using your client ID and client secret.
• A direct access token or provider-specific token where supported.

The available modes are defined by the service. If the provider authorization is cancelled, denied, or times out, the Profile is not ready for use. Retry the authorization and confirm that the provider granted the requested scopes.

When using a custom OAuth application, its redirect URLs, enabled APIs, consent configuration, and provider review requirements must match the provider's rules.

3. Configure the Connection

Enter the unique alphanumeric Connection Name and complete any service-specific fields.

Connection settings can include:

• An API URL and HTTP method.
• Request content type, headers, or default data.
• A sender address.
• A Square location.
• An MCP server URL, transport, and timeout.
• Google Drive files approved for the Connection.

Some services have no additional Connection fields. In those cases, the name and selected Profile complete the configuration.

Select Next to save the Connection. After creation, it appears in the Connections listing and becomes available to supported editor selectors.

Reusing Profiles

Profiles reduce duplicated credential configuration. A shared Profile is useful when several Connections intentionally use the same provider account.

Examples include:

• API Call Connections with different endpoints but the same authorization.
• SendGrid Connections with different sender addresses and the same API key.
• Google Connections that use the same authorized Google account and service scopes but approve different Drive files.

Profiles are shared by the development and published versions of the Project. They are not copied separately when the Project is published. Replacing credentials or reauthorizing a Profile can therefore affect every development and published Connection that uses it.

Before changing a Profile, identify its dependent Connections and test each affected workflow. A Profile cannot be deleted while any Connection refers to it, including a Connection that exists only in the currently published version.

Editing a Connection

Select a Connection and choose Edit.

Editing allows you to:

• Select another compatible Profile.
• Change Connection-specific settings.
• Update selected Google Drive files where applicable.

The service and Connection name remain fixed. To change either, clone or create a new Connection and migrate its consumers.

After editing:

1. Test the Connection in every context that uses it.
2. Verify provider scopes and environment.
3. Republish the Project when the change must affect the published application.

Cloning a Connection

Select a Connection and choose Clone to create another Connection with a new name.

Cloning copies:

• The service.
• The selected Profile.
• Connection-specific configuration.
• Access (Security) assignments.

Use cloning when creating a closely related Connection, such as a second endpoint, sender, location, or named use of the same provider account.

Cloning does not create an independent copy of the Profile. The original and clone continue to reference the same Profile unless one is edited to select another Profile.

After cloning, review all settings and permissions. A copied production URL, sender, location, or access policy may not be appropriate for the new Connection.

Deleting a Connection

Select a Connection and choose Delete, then confirm the operation.

Before deletion:

1. Search Page Flow and Cloud Flow for the Connection name.
2. Check Widgets and Page settings that may select it.
3. Check AI Agent capabilities or Knowledge Sources that may depend on it.
4. Check custom client and server code for the Connection name.
5. Replace or remove those references.
6. Test the affected workflows.

Deleting a Connection does not automatically rewrite blocks, code, or other configuration that refers to its name. Those consumers can fail when they next execute.

Deleting a Connection does not delete its Profile. Other Connections may use the same Profile, and the Profile may still supply authentication and authorization information to the published version of the deleted Connection.

Deletion affects the development version first. Until the Project is republished, the published Connection remains available and continues to use its Profile. Republish the Project to remove the Connection from the published version.

Deleting a Profile

A Profile can be deleted only when no development or published Connection refers to it. The Project Editor prevents deletion while the Profile is in use.

To remove a Profile safely:

1. Find every development Connection that uses the Profile.
2. Edit those Connections to select another Profile, or delete the Connections if they are no longer required.
3. If any affected Connection exists in the published Project, republish the Project. This updates or removes the published Connection reference.
4. Return to the Profile selection step for that service and select the unused Profile.
5. Choose the delete Profile action and confirm the deletion.

Deleting a development Connection is therefore not always enough to make its Profile deletable. If the Connection was published, its published copy continues to refer to the Profile until the next successful publish. The Profile can be deleted only after that reference, and any references from other Connections, have been removed.

Deleting a Profile removes its stored authentication and authorization information from the Project. It does not necessarily revoke the corresponding API key, access token, or authorization at the external provider. Revoke external credentials through the provider when required.

Connection Access

Select a Connection and choose Access (Security) to configure the Project User Groups allowed to perform its exposed operations.

The available operation rows are defined by the service. They can represent general Create, Read, Update, and Delete behavior or use service-specific labels such as:

• Invoke/Execute.
• Send Emails.
• Send Messages.
• Initiate Payments.
• Retrieve.

Only operations supported by the service appear.

Assigning Groups

For each operation:

1. Select its edit control.
2. Choose the Project User Groups that should be allowed.
3. Save the assignment.
4. Repeat for the other applicable operations.

Some operations prohibit Public access. Others display a warning because unauthenticated access can cause external changes or cost. Treat the warning as a security decision, not merely as a confirmation step.

For example, public access to a command that sends messages, invokes a paid API, or creates payment operations can be abused even when the surrounding Page appears harmless.

Access and Trusted Backend Logic

Connection Access is one part of the authorization model. Cloud Flow is trusted server-side logic and must still validate the caller, input, ownership, and business rules when exposing an integration through a Web Hook.

Do not rely on a hidden button or restricted Page as the only protection for an external operation. Enforce the required checks where the server performs the action.

For group identities and role levels, see User Groups. To create Project Users and assign their group membership, see Users. For Cloud Flow authorization, see Access and Security.

After changing Connection Access, republish the Project for the new policy to take effect in the published application.

Using Connection Commands

Not every service exposes commands. For services that do, each command declares whether it is supported from the client context, server context, or both.

Page Flow

Use these blocks:

Block	Purpose
Connection (connectionasstring)	Selects a configured Connection.
Connection Command (connectioncommandasstring)	Selects a command supported in the Page Flow context.
Execute Connection Command (connectioncommandcall)	Sends command data and runs the success or failure branch.

Page Flow initiates the request from the browser, but the command executes on the server. The command remains subject to its supported context and the Connection's Access policy.

Custom client JavaScript can use $io.system.connectionCommand(...) for the same supported command interface. See Client $io.system.

Cloud Flow

Cloud Flow can use Execute Connection Command for commands supported in the server context. Custom server JavaScript can use $io.system.connectionCommand(...).

Commands are not aliases for provider methods. Use only the command names and parameters documented for the service.

Using Connection Methods

Connection methods are server-only and are separate from commands.

Cloud Flow provides:

Interface	Use
Connection Function Call (connectionfunctioncall)	Visually invoke a supported method using a Connection, method name, and named-parameter object.
$io.system.connectionMethod(...)	Use the same generic calling convention from custom server JavaScript when service or method selection is dynamic.
Service-specific $io API	Directly call documented methods for a known provider from custom Cloud Flow code.

For custom code with a known service, prefer the documented service-specific API. See the Server API and the relevant service guide.

SDK Objects

Some services can provide an authenticated Node.js SDK or library object to Cloud Flow through $io.system.sdkLibraryObjectFromConnection(...).

SDK availability is independent of command availability. A Connection can provide an SDK object without exposing Page Flow commands.

Use only documented SDK service names and the SDK version supplied by the Cloud Flow runtime. An SDK service name is not necessarily the same as the Connection service identifier used by connectionCommand(...) and connectionMethod(...). For example, the Google Connection identifier is google, while its supported SDK service names include google.drive and google.sheets. The presence of a package in the curated require(...) list does not establish that it can be authenticated through a Connection.

See Node.js Runtime and SDK Libraries and $io.system.

Testing Connections

Test each Connection through its real invocation path. A successful Profile creation does not prove that every command or method has the required provider permissions.

Check:

• The intended Profile, provider account, and environment are selected.
• Required OAuth scopes or API permissions are granted.
• Connection settings such as URLs, sender addresses, locations, and selected files are correct.
• Allowed and denied Project Users receive the expected result.
• Success, provider error, timeout, and invalid-input paths are handled.
• The external provider shows the expected effect.

Preview and Test Mode do not prevent real external effects. Use provider test environments or controlled accounts whenever possible.

Troubleshooting

The Connection Is Not Available in a Selector

Confirm that:

• The Connection was saved successfully.
• The selector is being used in the correct Page Flow or Cloud Flow context.
• The service exposes the requested interface.
• The command supports the current context.

OAuth Authorization Did Not Complete

Check the provider window for an error, confirm the requested scopes, and verify custom client settings when applicable. Retry Profile creation or authorization after correcting the provider configuration.

The Operation Returns an Access Error

Review the Connection's Access (Security) assignments and the current Project User's groups. Also verify provider-side permissions and scopes; Project access does not grant permissions that the external account does not have.

The Development Version Works but the Published Version Does Not

Confirm that the latest Connection and Access changes were followed by a successful Project publish. Profiles are shared by the development and published versions, so also verify that the shared credentials, scopes, and provider restrictions are valid for the published application.

A Profile Cannot Be Deleted

The Profile is still referenced by at least one Connection. Check both the development and published versions. If the Connection was removed or changed only in development, publish the Project to update the published version, then try deleting the Profile again.

The Wrong External Account Was Used

Check the selected Connection and Profile. Similar names can conceal an environment or account mismatch. Use explicit names and keep test and production Profiles separate.

Related Documentation

• Integrations
• Connection Services
• Page Flow Connection Blocks
• Cloud Flow Connection Blocks
• Using Connections from Cloud Flow
• Server API
• Users
• User Groups