Deploying sites from your AI tool

Netlify is so proud to work with many amazing partners and companies in our ecosystem to allow developers to ship ideas faster. With the rise of developers leveraging AI tools for creating web experiences, we’ve partnered with so many amazing providers to help take these ideas and drive them all the way to production.

This guide is for those teams looking to provide tools for developers and non-developers alike to create web experiences. Within this guide we will break down the process of leveraging Netlify to deploy sites on behalf of end users and give them the control to claim these sites in the future.

#The value of deploying AI-generated sites

We’ve found that creating new experiences and prototypes inside of tools are great but creators want a way to show the world (or just their team) what they’ve created. In many cases, the sole purpose that these creators are using these tools for is to bring their vision to the world, create their landing pages, and engage with their audience.

Once they get to that point, these creators are looking to have a link, custom domains, access control, analytics, etc. This is where Netlify comes in to unlock the full platform for you and your customers to build on.

#Deployment process from a high level

Ultimately, the Netlify platform can be very flexible and supports many patterns and usecases for tools deploying to the web. To keep the scope of the guide simple, we will focus on the most common pattern we see.

The desired experience usually looks like the following:

1. Creator generates a site or web-related resource using a tool (usually an AI tool).
2. This tool allows them to publish their creation once they are ready.
3. The creator is given a link to their site to review and share.
4. The tool can go on to make updates automatically or based on prompting from the creator.
5. The tool offers some way for the customer to download their resources and continue outside the tool.

Partners come to Netlify to solve steps 3 through 5.

Deploying to Netlify as a provider works like this:

1. Create a Netlify site under your umbrella account (if it doesn’t already exist).
2. Upload the assets that represent the site’s deploy via the API. This process provides the URL that can be given to the end user.
3. Generate a “claim” URL to share with the creator. This allows users to take over ownership of a site to keep full control over it.
4. After a user claims their site, creators can continue to make changes to the site that was generated via your tool.

#Becoming a partner

While you don’t have to be a Netlify partner to build this, we’ve been fortunate enough to help back some of the most disruptive tools in the industry. From Cognition.ai’s Devin, Stackblitz’s Bolt.new, and so many more. These partners leverage Netlify to take on the painful parts of allowing customers to ship content to the web while they focused on a great AI creator experience.

Some of the benefits partners see:

• Zero friction deployments (No need to force users to have Netlify accounts before starting).
• Customer sites that have access to a cutting edge platform and globally performant infrastructure.
• Massive rate limits (we don’t slow you down when growth hits).
• Help from our best-in-class support for fraud and abuse detection and mitigation.
• Access to engineering support focused on supporting partners leveraging Netlify to deploy websites.
• Co-marketing to celebrate and showcase your offerings.

As partners, we have opportunities to find mutual agreements to help your tools and services ship and grow without the worry of causing a financial burden has you start to scale. In most cases, we’ve found ways to support our deploy target partners with zero cost to them. This is a massive opportunity to work with us as a partner to let us help you deliver your vision.

Building a tool that could benefit from this? Let’s chat!

#Initial setup

This set up makes sure you have the right information available to start making authenticated API calls.

#Netlify team information

As a partner, you’ll need to have a Netlify account. Create one here if you don’t already have one. If you already have a Netlify account, it’s usually preferred to create a new account dedicated to being the umbrella for all of the user generated sites/resources.

When you have your account ready. Grab the team slug . This is found under the general team information settings. More on how to access the slug in our documentation.

#Create a new Netlify OAuth app

Firstly, OAuth apps on Netlify take actions leveraging the user identification of the user that creates the app. Therefore the user account that is creating the app should be a permanent team user or one that is aliased to be permanent. For example, operations-user@example.com that will always exist. This step is important for when you’re ready to go to production, if you’re just prototyping, any user on your Netlify account will be fine. When ready to go to production you can create a new OAuth app with the right user and swap the details below.

With your Netlify user, visit the user settings page on the Netlify UI. From there you will find an OAuth applications. Select “Create new” and fill in the details. If you’re only using the app to create site deploys, you won’t need a redirect URI. If you wish to allow developers to link their Netlify account with your system (not strictly required for deployments), then you can also provide a redirect URI where you can get the access token from the user.

After creating a new one, you will have a Client ID and a Secret assigned to your application. These will be used with identifying yourself in API calls.

#Create a personal access token

Using the same user that controls the OAuth app, you will generate a personal access token. For APIs that are making changes to your account (like adding new sites) this token authenticates those requests.

To create a new token, navigate to personal access tokens section of the user’s settings page. When you’re creating the token, be sure to select the SAML checkbox if you log in with SSO. If you set an expiry, you will be responsible for eventually rotating the token before it expires.

🎉 You have everything you need to start building creating sites for users. Let’s dive into the code that would make this happen.

#Authenticating to the API

Unless explicitly noted, all calls to https://api.netlify.com/ require an Authorization header that contains the personal access token that was generated in the setup steps.

Authorization: `Bearer ${PERSONAL_ACCESS_TOKEN}`

#Creating sites

When following the most common pattern, sites are put under the partner’s account until they are claimed. To do this, we make an API call to Netlify that creates a site under the partner’s team account.

const site = await fetch("https://api.netlify.com/api/v1/sites", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PERSONAL_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // what's the name of your tool. lowercase, no spaces.
    created_via: TOOL_NAME,
    // the team slug that you identified in the setup steps
    account_slug: TEAM_SLUG,
    // what should the site's name be? We can generate one if
    // this is missing. Or you can control it. Make it unique.
    name: `${Date.now()}-via-ai`,
    // a unique value that's tied to this specific user. This value
    // is used in the claim link generation to ensure that your assignment
    // of this value matches what's in a claim link. Usually this is
    // a user's account id or GUID that is tied to this user.
    session_id: USER_SESSION_ID,
  })
});

This will create a site under the partner’s account. At this point, we have not uploaded or deployed any files yet but just created the “site” where everything is linked from.

The session_id is very important here. It’s an identifier that you are assigning to this site as a double verification signal for the correct assignment. When you create a claim URL later, this same session_id will be used. By using this flow, it forces more correctness that 1) you are allowing this site to be claimable and 2) this is the expected owner. Unless you’re using overlapping identifiers, this pattern will ensure you’re not allowing incorrect site claiming to end users.

#Create a new deploy

Now that we have a site, we need to deploy something to it.

#Zipping the files to deploy

The Netlify API to deploy static files supports sending a .zip compressed file that contains all of the files. To simplify this, we can use a package such as archiver to handle the async compression logic. Here’s a utility method that can do all of this for us.

import { createWriteStream } from "fs";
import archiver from "archiver";

function zipFiles({zipPath, glob}: {zipPath: string, glob: string}) {
  return new Promise((resolve) => {
    // create a file to stream archive data to.
    const output = createWriteStream(zipPath);
    const archive = archiver('zip', {
      zlib: { level: 9 } // Sets the compression level.
    });

    // listen for all archive data to be written
    // 'close' event is fired only when a file descriptor is involved
    output.on('close', function () {
      resolve({ zipPath });
    });

    // good practice to catch this error explicitly
    archive.on('error', function (err) {
      throw err;
    });

    // pipe archive data to the file
    archive.pipe(output);

    // add all of the files that match the pattern
    archive.glob(glob);

    archive.finalize();
  });
}

With this in place, we can select the files that need to be uploaded. With AI tools, this is usually content that’s generated and is in memory. In our example, we’re assuming the files are written to disk and we’re using the filesystem to load them for zipping.

Using this utility then looks like the following:

await zipFiles({
  // relative to where this process is ran, what file patterns
  // should be included in this deploy?
  glob:'public/**/*',
  // where should the zip file go on disk?
  zipPath: 'site.zip'
});

This snippet will grab all of the files in the public directory and subdirectories and put them into a single .zip file at the location site.zip Later, our code will pull this .zip file from disk. There’s no requirement to read/write from disk to achieve this, it’s just the path we took for this examples

#Deploying the files

With our .zip file containing the site’s files, we can now upload these files to be the latest deploy for our Netlify site.

import { createReadStream } from "fs";

const deploy = await fetch(`https://api.netlify.com/api/v1/sites/${site.id}/deploys`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PERSONAL_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  // the disk location of our .zip file from before
  body: createReadStream('site.zip'),
  duplex: "half",
});

This creation process generates a new deploy and assigns it to the site. Using this API is the way your tool can create new deploys for the same site. By default, the latest deploy will be whats in production.

🎉 Yay! You now have a deployed site generated from your tools that can be shared and used by anyone!

#Allowing users to claim a site

This is where things get really interesting. This is where you can allow a creator to take ownership of their site so that they can take things further on the hosting side while your tool retains access to continue deploying.

Importantly, up until this point, the site has been built and deployed under the partner’s Netlify account. This is usually that umbrella account for collecting all of the user generated sites and resources. The claim process is transferring the site from the partner’s account to the creator’s account.

Doing so is as simple as creating a special link to give to the creator. This link contains all of the context necessary to initiate the transfer. To achieve this, we create a signed JSON Web Token (JWT) that encodes the data in a signed format.

import jwt from 'jsonwebtoken'

const token = jwt.sign({

  // remember that OAuth app we set up? this is the client ID from that app
  client_id: OAUTH_CLIENT_ID,

  // this is the user unique session id that we used when we created the
  // site in the first API call. These values must be the same.
  session_id: USER_SESSION_ID

}, OAUTH_CLIENT_SECRET);

// adding your tool's name helps with attribution of new sites to your tool
const claimLink = `https://app.netlify.com/claim?utm_source=${TOOL_NAME}#${token}`

After claiming the site is put under the creator’s Netlify account but you still retain the ability to push updates to the site after it has been claimed.

#Updating the site after claims

Now that the user has decided to claim the site and take control. There are two options to continue making updates to the site.

1. Because your app is the creator of the site, it will still retain the ability to push deploys. This access is limited to making changes to the sites that you’ve created.
2. Use the same Netlify OAuth app that you created to request access to the creator’s Netlify account. This allows you to create new sites under the user’s account and access more information about the site on behalf of the user.

To use your Netlify OAuth app to get a user access token to make API calls to the user’s Netlify account. Follow these steps:

• Update your Netlify OAuth app with the Netlify UI to have a redirect URI.

• Your app must redirect the user to the authorization screen on Netlify with your app details. You’ll use the redirectURI

  const oAuthLink = 'https://app.netlify.com/authorize?' +
              'client_id=' + clientId +
              '&response_type=token' +
              '&redirect_uri=' + redirectURI;

• Opening this link will prompt the user to allow access and the user will be redirected to the redirect URI and the user access token will be within the URL as a hash fragment. https://myservice.com/my-redirect-path#{NETLIFY_TOKEN} this token is the access token that will allow you access to the user’s Netlify account.

#Success!

At this point, we’ve implemented one of the most common flows for targeting Netlify to manage the deploys for partner tools and services. There’s so much more that you can do with this once there is an established connection.

Ready to dive into the code that uses all of this? Check out our example Github repo that uses these APIs to achieve all of the above.

If you’re interested in learning how a partnership with us could work, let’s talk!