Inter-app Communication¶

This topic describes how one Snowflake Native App can communicate with another Snowflake Native App using inter-app communication (IAC).

Inter-app Communication: Overview¶

Inter-app communication (IAC) allows a Snowflake Native App to provide additional functionality to other Snowflake Native Apps in the same consumer account by providing access to functions and procedures that other apps can call.

For example, a Snowflake Native App that resolves customer IDs can help other Snowflake Native Apps enhance customer data by joining data sets from different vendors.

IAC provides the infrastructure for two or more independent apps to communicate with each other while respecting their needs for management and security. App developers enable IAC for their app by doing the following:

Creating interfaces
Using app roles to control access to the interfaces.
Choosing synchronous or asynchronous interaction. Synchronous interaction uses stored procedures or functions that other apps can call directly, while asynchronous interaction provides access to request results that are stored in tables or views, which other apps can poll to check for results.

For examples of setup files for IAC client apps, see Examples.

Terminology¶

IAC uses the following terms:

Client: The app that initiates the connection request and calls the server app’s functions and procedures.
Server: The app that provides access to its functions and procedures using app roles.
Consumer: The user who installs the client and server apps.
Application configuration: A SQL object that the client app uses to request the name of the server app.
Application specification: A SQL object that the client app creates to request a connection to the server app. IAC uses an application specification of type CONNECTION. For information about app specifications, see Overview of app specifications.

Workflow for Inter-app communication¶

Establishing and using a connection involves a handshake process between the client app and the server app.

Identify the target app: The client app creates a configuration definition object to request the name of the server app. The consumer detects incoming requests, and updates the configuration definition object with the name of the server app.
Request and approve a connection: The client app creates an application specification to request a connection to the server app, and the consumer approves the connection request.
Communicate with the Server App: The client app calls the server app’s procedures or functions.

Identify the target app¶

Before a client app can communicate with a server app, it must first identify the exact name of the app. Because the consumer can choose a custom name for an app during installation, the client app must first identify the exact name of the server app.

The client app’s setup script creates a CONFIGURATION DEFINITION object to request this information.

The following example shows how the client app’s setup script creates a CONFIGURATION DEFINITION object to request the name of the server app:

ALTER APPLICATION
  SET CONFIGURATION DEFINITION my_server_app_name_configuration
    TYPE = APPLICATION_NAME
    LABEL = 'Server App'
    DESCRIPTION = 'Request for an app that will provide access to server procedures and functions. The server app version must be greater than or equal to 3.2.'
    APPLICATION_ROLES = (my_server_app_role);

Copy

The following example shows how the consumer checks for incoming configuration definition requests:

SHOW CONFIGURATIONS IN APPLICATION my_server_app_name;

Copy

This command returns results similar to the following:

name                             | created_on              | updated_on              | type               | ...
my_server_app_name_configuration | 2026-02-09 10:00:00.000 | 2026-02-09 10:00:00.000 | APPLICATION_NAME   | ...

The consumer then uses the following command to set the server app name in the client app’s configuration definition:

ALTER APPLICATION my_client_app_name
  SET CONFIGURATION my_server_app_name_configuration
  VALUE = MY_SERVER_APP_NAME;

Copy

Request and approve a connection¶

Once the client app has the name of the server app, it creates an APPLICATION SPECIFICATION to request a connection to the server app.

The following example shows how to create an APPLICATION SPECIFICATION for a connection to the server app named my_server_app_name:

ALTER APPLICATION SET SPECIFICATION my_server_app_name_connection_specification
  TYPE = CONNECTION
  LABEL = 'Server App'
  DESCRIPTION = 'Request for an app that will provide access to server procedures and functions. The server app version must be greater than or equal to 3.2.'
  SERVER_APPLICATION = MY_SERVER_APP_NAME -- server name obtained from Step 1
  SERVER_APPLICATION_ROLES = (my_server_app_role);

Copy

By creating the application specification, the client app is requesting to be granted the server app roles specified in the app specification.

Note

The values given for LABEL and DESCRIPTION in the app specification must match the values given for LABEL and DESCRIPTION in the CONFIGURATION DEFINITION object created in Step 1. If the values do not match, the connection won’t display properly in Snowsight.

To create an efficient connection workflow, we recommend that the client app create the application specification in the before_configuration_change synchronous callback. This callback is run when the ALTER APPLICATION SET VALUE command is run. For more information, see before_configuration_change. For information about callbacks, see Callbacks.

Once the client app has created the app specification, the consumer approves the connection request.

Approving the connection request using SQL¶

The following example shows how the consumer approves the connection request using SQL:

ALTER APPLICATION my_server_app_name
  APPROVE SPECIFICATION my_server_app_name_connection_specification
  SEQUENCE_NUMBER = 1;

Copy

Approving the connection request using Snowsight¶

To view and approve connection requests in Snowsight, do the following:

Sign in to Snowsight.
Select the app. A section titled App connections appears. Each pending connection shows the name or label for the connection, a brief description of the connection, and a Review button.
Click the Review. The details of the connection request appears.
Select the target app from Select from your apps.
Click Next. The following information appears:
- A diagram showing the two apps to be connected.
- The details of the connection.
- The permissions that will be granted between the apps
- An Approve Connection toggle switch. The switch is set to On.
To approve the connection, leave the toggle switch set to On, and click Save. The updated connection list appears showing the status of the connection.
To decline the connection, switch the toggle switch to Off, or click Cancel.

Post-approval¶

When the consumer approves the connection request, the Snowflake Native App Framework grants the requested server app roles to the client app. The approval also grants USAGE on the client app to the server app. This allows the server app to be aware of what client apps are connected to it.

When the consumer approves the connection request, the following callbacks are triggered in the client and server apps, respectively:

after_server_connection_change is triggered in the client app
after_client_connection_change is triggered in the server app

These callbacks allow the server and client apps to perform additional actions when the connection is established.

For more information about approving application specifications, see the following topics:

Communicate with the server app¶

Once the connection is established and the client app is granted the requested server app roles, the client app can communicate with the server app.

Note

Before calling server app methods, the client app should retrieve the server app’s name at runtime from the approved application specification, to ensure it uses the correct name in case the server app is renamed. The following example shows how to retrieve the server app’s name at runtime:

SHOW APPROVED SPECIFICATIONS ->>
  SELECT PARSE_JSON("definition"):"SERVER_APPLICATION"::STRING
  FROM $1
  WHERE "name" = MY_SERVER_APP_NAME_CONNECTION_SPECIFICATION;

Copy

The client app can communicate with the server app synchronously or asynchronously.

Synchronous communication involves invoking the server app’s procedures or functions directly.
Asynchronous communication involves using a queue stored in a data object, such as a table. For example, the server app can provide a procedure to insert records into a table as requests, which the server app then processes periodically. The client app can then use a different server-provided procedure to check the table for results.

The following example of a synchronous operation shows a client app calling a server app’s procedure using Python:

session.call("server_app_name.customer_schema.get_customer_data", customer_id);

Copy

The following example of an asynchronous operation shows a client app calling a server app’s procedure using Python. The client app calls the server app’s procedure, which creates a request in a table, which the server app then processes. The client app can poll the table to check for updated records for results.

session.call("server_app_name.customer_schema.request_customer_data_async", customer_id);

Copy

The client app can then poll the table to check for updated records for results:

session.call("server_app_name.customer_schema.check_customer_data_requests_async", customer_id);

Copy

Managing connections¶

To view existing connections in Snowsight, do the following:

Sign in to Snowsight.
In the navigation menu, select Catalog » Apps.
Select the app. All app connections are shown in a section titled Configurations. Below that section, there is a sub-section titled Application connections.
To modify a connection, click the pencil icon for the connection. You can change the following:
- Which app is connected to the app
- The approval status of the connection
To view the connected app, click the View app button.

Security considerations¶

When approving a specification request, consumers should be aware that granting server app access to a client app can elevate the privileges the client app has. For example, if a server app has external access, the client app might gain indirect access to the Internet or other external resources through the server app. If the server app is a client app of another server app, the client app may be able to access the resources of the other server app through the first server app.

Consumers should inspect the capabilities and privileges of the server app before approving a connection. We recommend that you use an admin role (for example, ACCOUNTADMIN) to inspect the capabilities of the server. Example SQL commands to inspect the capabilities and privileges of the server app include, but are not limited to the following:

SHOW GRANTS TO APPLICATION: This command lists what grants on the client app have been granted to the server app.
SHOW PRIVILEGES IN APPLICATION: This command lists what potential account-level privileges could be granted to the client app.
SHOW REFERENCES IN APPLICATION: This command lists references that the client app could potentially use without using grants.
SHOW SPECIFICATIONS IN APPLICATION: This command lists the application specifications that the consumer has approved, including external access integrations (EAIs), security integrations, shares, listings, and connections.

SQL Reference¶

The following SQL commands are used to manage inter-app communication.

ALTER APPLICATION SET SPECIFICATION: Creates an app specification that the server app uses to grant access to its functions and procedures to the client app.
ALTER APPLICATION DROP SPECIFICATION: Deletes an app specification.
ALTER APPLICATION … { APPROVE | DECLINE} SPECIFICATION: Approves or declines an app specification request.
SHOW SPECIFICATIONS: Lists all of the application specifications in an app.
DESCRIBE SPECIFICATION: Describes the app specifications for an app.
ALTER APPLICATION SET CONFIGURATION DEFINITION: Creates or updates an application configuration (a key-value pair) that requests the name of another application from the consumer.
ALTER APPLICATION DROP CONFIGURATION DEFINITION: Deletes an application configuration.
ALTER APPLICATION SET CONFIGURATION VALUE: Sets a value in an application configuration.
ALTER APPLICATION UNSET CONFIGURATION: Unsets the value to the specified application configuration.
SHOW CONFIGURATIONS: Lists all of the application configurations in an app.
DESCRIBE CONFIGURATION: Describes the details of an application configuration.
IS_CONFIGURATION_SET (SYS_CONTEXT function): Returns whether or not the configuration has a value set.
GET_CONFIGURATION_VALUE (SYS_CONTEXT function): Returns the current value of the configuration.
SHOW GRANTS TO APPLICATION: Lists all the privileges and database/application roles granted to the specified app.
SHOW GRANTS TO APPLICATION ROLE: Lists all the permissions that the application role has.
SHOW GRANTS OF APPLICATION ROLE: Lists all the roles and applications to whom the specified application role is granted.

Callbacks¶

The Snowflake Native App Framework provides callbacks to help manage the connection lifecycle. You can use these callbacks to enhance your app’s functionality and improve the connection workflow.

To use callbacks, add them to the lifecycle_callbacks section of the manifest file, as in the following example:

lifecycle_callbacks:
    before_configuration_change: app_schema.before_config_change_callback

Copy

Types of callbacks¶

The Snowflake Native App Framework provides synchronous and asynchronous callbacks.

Synchronous callbacks¶

Synchronous callbacks are called as part of the triggering SQL command. Synchronous callbacks block the calling SQL command. If the callback returns an error, the command will return an error, and the callback’s error message will be returned as part of the SQL error message of the command.

Synchronous callbacks run in a warehouse, so the calling procedure must have a session warehouse set.

Asynchronous callbacks¶

Asynchronous callbacks run in the background, after the calling SQL command completes. Asynchronous callbacks do not block the calling SQL command, and errors in asynchronous callbacks are not returned by the calling command.

Return values from asynchronous callbacks are ignored.

Note that the execution order of asynchronous callbacks is not guaranteed, so your app should not rely on the order of asynchronous callbacks to perform its operations.

To ensure that an asynchronous callback has the most current information, the callback signature doesn’t provide state or status information. Instead, the callback should retrieve the most current information using the appropriate SQL commands, such as SHOW CONFIGURATIONS or SHOW SPECIFICATIONS. See the description for each asynchronous callback following for more information.

Asynchronous callbacks are usually used for notification or tracking.

Callback reference¶

For a list of callbacks used by IAC, see Inter-App Communication Callback Reference.

Specification vs. connection Callbacks¶

Both after_specification_change and after_server_connection_change are run when a specification is approved or declined. The differences between the two callbacks are as follows:

after_specification_change is part of the application specification framework. It is only triggered when the consumer approves or declines a specification request.
after_server_connection_change is part of the inter-app communication framework. It is triggered by any operation that directly or indirectly impacts the connection state of application specification, including the following: - Approving a spec - Declining an approved spec - Dropping an approved spec - Dropping the server app

We recommend that you use after_server_connection_change when the response action should be semantically associated with connection establishment/loss rather than specification approval/decline itself. This should also help track the connection better as it also gets triggered at deletion of the server app.

For any other types of Application Specifications, after_server_connection_change is not relevant so after_specification_change should be used.

For handling only the approval or decline of a specification request that is not related to connection establishment or loss, we recommend that you use the after_specification_change callback.

Examples¶

The following examples show how to configure an app to use inter-app communication.

Example: Setup script and manifest files¶

The following example shows a client app’s setup script (setup.sql):

CREATE OR ALTER VERSIONED SCHEMA app_schema;

-- before config value is saved, create the connection request
CREATE OR REPLACE PROCEDURE app_schema.before_config_change_callback(config_name STRING, config_value STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
DECLARE
    spec_name VARCHAR;
    existing_target VARCHAR;
BEGIN
    IF (config_value IS NOT NULL AND config_name = ''CALCULUS_PLUGIN_NAME'') THEN
        SHOW SPECIFICATIONS;
        SELECT PARSE_JSON("definition"):SERVER_APPLICATION::STRING
            INTO existing_target
            FROM TABLE(RESULT_SCAN(LAST_QUERY_ID()));

        IF(existing_target IS NOT NULL AND UPPER(existing_target) != UPPER(config_value)) THEN
            EXECUTE IMMEDIATE ''ALTER APPLICATION DROP SPECIFICATION CONNECTION_'' || UPPER(existing_target);
        END IF;

        spec_name := ''CONNECTION_'' || UPPER(config_value);
        EXECUTE IMMEDIATE
        ''ALTER APPLICATION SET SPECIFICATION '' || spec_name || ''
            TYPE = CONNECTION
            LABEL = ''Calculus Plugin''
            DESCRIPTION = ''''Request for an application that will provide Calculus APIs. The calculus app must be >= 3.2''''
            SERVER_APPLICATION = '' || config_value || ''
            SERVER_APPLICATION_ROLES = (calculus_api_user)'';
    END IF;
RETURN ''success'';
END;
$$;

CREATE APPLICATION ROLE IF NOT EXISTS math_app_user;
GRANT USAGE ON SCHEMA app_schema TO APPLICATION ROLE math_app_user;
ALTER APPLICATION SET CONFIGURATION DEFINITION calculus_plugin_name
    TYPE = APPLICATION_NAME
    LABEL = ''Calculus Plugin''
    DESCRIPTION = ''Request for an application that will provide Calculus APIs. The calculus app must be >= 3.2''
    APPLICATION_ROLES = (math_app_user);

Copy

The following example shows a client app’s manifest file (manifest.yml):

manifest_version: 2

artifacts:
  setup_script: setup.sql

lifecycle_callbacks:
    before_configuration_change: app_schema.before_config_change_callback

Copy

Note the following about the preceding code example:

The callback fields before_configuration_change and after_configuration_change do not require that the procedure be granted any application role. The callback procedures can be internal to the app, and not be runnable by the consumer account.
In the before_configuration_change callback, the app checks for an existing connection specification matching the configuration’s previous value, and drops it if it exists. The callback then creates a new connection specification for the newly provided server app name. Creating a new connection when the server name is set prevents duplicate connection specifications from being created.