Installation flow
When a user installs your extension on a team, they authorize the extension to perform Netlify actions on their behalf based on the permission scopes you configure for your extension.
This authentication allows the extension to call Netlify endpoints and is necessary for things such as running a build event handler on a site, installing a connector on a data layer, configuring environment variables, and interacting with any other Netlify API.
Extensions are installed on teams, not sites
Users install extensions on the team level and can then configure them for a specific site or data layer based on what your extension requires. If your extension includes a build event handler, function injection, or edge function injection, the extension is still installed on the team but it will run on all sites on that team. We recommend that you include conditional logic to check that the extension is configured before running build event handlers and injecting functions or edge functions.
How users install extensions
When an extension is published, users can access the extension’s details page in the Netlify UI — through a direct link, in the section for extensions created by your team, or in the extensions directory if the extension is listed.
On the details page, users select Install to install the extension on their team and authenticate it. After the user authenticates, the extension will have access to the configured permission scopes.
After the extension is installed, the user may need to configure some additional settings to use your extension. You can create the surfaces for these using extension UI and Netlify will render these surfaces in various places across the Netlify UI.
Your extension UI can use endpoints to make API calls to third-party APIs as needed during that configuration flow.
Configure your extension for OAuth
While this document covers the Netlify authentication that occurs when users install your extension, you also have the option to ask users to authenticate through an OAuth identity provider as part of your extension’s configuration step. This may be necessary if your extension must make authenticated requests to your APIs.
Learn more about how to use OAuth with your extension.
Permission scopes
As mentioned above, when a user installs and authenticates your extension in the Netlify UI, your extension will have access to certain resources based on the configured permission scopes. It‘s important to specify the correct permission scopes to support any logic you might want to perform.
The following resources are available with read and write permission scopes:
Set permission scopes
There are multiple ways to set permission scopes for your extension.
When you create your extension:
- If you use the SDK’s guided flow to create a new extension, we will add the appropriate scopes based on the boilerplate you generate.
- If you use the SDK’s guided flow to create a new extension and choose not to use boilerplate code, we’ll prompt you to specify permission scopes separately.
When you publish your extension:
- You can specify permission scopes in the Netlify UI when you publish your extension.
Test your extension’s installation flow
Use the extension UI preview mode to preview your extension card and test your install flow. This preview mode allows you to test your install flow without publishing your extension.
Learn more about how users find and install extensions
If you want to learn more about how users find, install, and interact with extensions, review the following resources:
- Publish overview: extensions in the Netlify UI - written for extension authors, this page outlines the different ways extensions are presented in the Netlify UI.
- Extensions and integrations overview - written for extension users, this page in the Netlify user docs focuses on how users can find, install, and manage extensions on Netlify.