Snowflake API Integrations: Building External Function Connectivity

API Integration is the Snowflake object that holds the authentication and connection settings used to safely call external REST APIs from External Functions. It supports AWS API Gateway, Azure API Management, and Google Cloud API Gateway, so you can invoke external services such as ML inference, geocoding, or translation directly from a SQL query.

API Integration x External Function Architecture

An API Integration establishes the authentication channel between Snowflake's Cloud Services Layer and the cloud provider's API Gateway. The actual data flow looks like this:

SQL query
  -> Virtual Warehouse (calls External Function)
    -> Cloud Services Layer (API Integration authentication)
      -> API Gateway (AWS / Azure / GCP)
        -> Backend (Lambda / Azure Functions / Cloud Functions)
          -> Response returned to Snowflake

The role of an API Integration is to establish the trust relationship between Snowflake's service account and the API Gateway's access controls. The actual HTTP requests are issued by the External Function itself.

Creating an API Integration for AWS

-- API Integration for AWS API Gateway
CREATE OR REPLACE API INTEGRATION aws_ml_api
  API_PROVIDER = aws_api_gateway
  API_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/snowflake-api-role'
  API_ALLOWED_PREFIXES = ('https://abc123.execute-api.us-east-1.amazonaws.com/prod/')
  ENABLED = TRUE;

-- After creation, fetch Snowflake's IAM info
DESCRIBE INTEGRATION aws_ml_api;
-- -> Check API_AWS_IAM_USER_ARN and API_AWS_EXTERNAL_ID
-- -> Configure these in the IAM role trust policy on the AWS side

Configuring the AWS IAM Role Trust Policy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "<API_AWS_IAM_USER_ARN>"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "<API_AWS_EXTERNAL_ID>"
      }
    }
  }]
}

Creating an API Integration for Azure

-- API Integration for Azure API Management
CREATE OR REPLACE API INTEGRATION azure_translate_api
  API_PROVIDER = azure_api_management
  AZURE_TENANT_ID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  AZURE_AD_APPLICATION_ID = 'f1e2d3c4-b5a6-7890-abcd-ef0987654321'
  API_ALLOWED_PREFIXES = ('https://my-apim.azure-api.net/translate/')
  ENABLED = TRUE;

-- Get AZURE_MULTI_TENANT_APP_NAME via DESCRIBE INTEGRATION
-- Grant the service principal the right permissions in Azure AD

Creating an API Integration for GCP

-- API Integration for Google Cloud API Gateway
CREATE OR REPLACE API INTEGRATION gcp_geocode_api
  API_PROVIDER = google_api_gateway
  GOOGLE_AUDIENCE = 'https://my-gateway-abc123.uc.gateway.dev'
  API_ALLOWED_PREFIXES = ('https://my-gateway-abc123.uc.gateway.dev/geocode/')
  ENABLED = TRUE;

-- Get API_GCP_SERVICE_ACCOUNT via DESCRIBE INTEGRATION
-- Grant this service account the Invoker role on the GCP side

Cloud-by-Cloud Configuration Comparison

Creating and Calling an External Function

-- Create an External Function and bind the API Integration
CREATE OR REPLACE EXTERNAL FUNCTION sentiment_analysis(text VARCHAR)
  RETURNS VARIANT
  API_INTEGRATION = aws_ml_api
  AS 'https://abc123.execute-api.us-east-1.amazonaws.com/prod/sentiment';

-- Call the External Function from a SQL query
SELECT
  review_id,
  review_text,
  sentiment_analysis(review_text) AS sentiment_result
FROM product_reviews
LIMIT 100;

-- Batch processing: persist the results with INSERT INTO ... SELECT
INSERT INTO product_reviews_enriched
SELECT
  review_id,
  review_text,
  sentiment_analysis(review_text):sentiment::VARCHAR AS sentiment,
  sentiment_analysis(review_text):confidence::FLOAT AS confidence
FROM product_reviews;

Security Design Highlights

• Keep API_ALLOWED_PREFIXES minimal: avoid overly broad, wildcard-like prefixes and allow only the endpoint paths you actually need.
• Layer on API_BLOCKED_PREFIXES for finer control: use it when you need to exclude specific paths from within an allowed prefix.
• Manage USAGE privileges: limit which roles get USAGE on the API Integration and revoke it from roles that no longer need it.
• Layer backend-side authentication too: configure API key checks or OAuth2 token validation at the API Gateway as well, so you have defense in depth.

API Integration Management Commands

-- List
SHOW API INTEGRATIONS;

-- Detail
DESCRIBE INTEGRATION aws_ml_api;

-- Disable (blocks all External Function calls using it)
ALTER API INTEGRATION aws_ml_api SET ENABLED = FALSE;

-- Re-enable
ALTER API INTEGRATION aws_ml_api SET ENABLED = TRUE;

-- Drop (drop all referencing External Functions first)
DROP API INTEGRATION aws_ml_api;

Troubleshooting

Check Your Understanding

Frequently Asked Questions