Skip to content
Netlify SDK DocsNetlify SDK Docs1.13.2

Use cases for the Integration API

Netlify’s Integration API allows you to make integrations with Netlify. This page explains some common use cases for the Integration API.

Enable or disable integrations

Using the Integration API is the only way to enable or disable integrations. For every integration, we automatically generate enable and disable logic that provides the necessary authentication from the integration user.

Beyond this basic logic, you can customize the flow for enabling or disabling an integration with additional logic. This is a required step for publishing integrations with Connectors or Build Event Handlers.

Use a custom integration context

The Integration API allows you to set a custom integration context. This context is a JSON object that can be used to store any data you want on either a site or team level.

Set a custom integration context for a site

To set a custom integration context for a site, take the following steps:

  1. Add an API handler.
  2. Call the client.updateSiteIntegration method. This method takes the siteId and the context as arguments. The context is a JSON object that can contain any data you want.
// src/index.ts
import { NetlifyIntegration } from "@netlify/sdk";

const integration = new NetlifyIntegration();

integration.addApiHandler("cool-function", async (event, context) => {
  const { client, siteId } = context;

  await client.updateSiteIntegration(siteId, {
    custom_field: "custom_value",
  });

  return {
    statusCode: 200,
  };
});

Set a custom integration context for a team

To set a custom integration context for a team, take the following steps:

  1. Add an API handler.
  2. Call the client.updateTeamIntegration method. This method takes the teamId and the context as arguments. The context is a JSON object that can contain any data you want.
// src/index.ts
import { NetlifyIntegration } from "@netlify/sdk";

const integration = new NetlifyIntegration();

integration.addApiHandler("cool-function", async (event, context) => {
  const { client, teamId } = context;

  await client.updateTeamIntegration(teamId, {
    custom_field: "custom_value",
  });

  return {
    statusCode: 200,
  };
});

Retrieve a custom integration context for a site or team

After setting a custom integration context for a site or a team, you can retrieve it by taking the following steps:

  1. Add an API handler.
  2. Call the client.getSiteIntegration method to retrieve the custom integration context for a site.
  3. Call the client.getTeamIntegration method to retrieve the custom integration context for a team.
// src/index.ts
import { NetlifyIntegration } from "@netlify/sdk";

const integration = new NetlifyIntegration();

integration.addApiHandler("cool-function", async (event, context) => {
  const { client, teamId, siteId } = context;

  // This retrieves the custom integration context for the site with the given siteId
  const { custom_field } = await client.getSiteIntegration(siteId);
  // This retrieves the custom integration context for the team with the given teamId
  const { custom_field } = await client.getTeamIntegration(teamId);

  return {
    statusCode: 200,
  };
});

Documentation

Visit our API reference docs for more information about the methods and properties available to you: