Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Get started with OAuth

This page will help you configure your integration to work with your OAuth identity provider, add an OAuth card element to your integration UI, and add logic to use the OAuth token on API requests while the integration runs.

Prerequisites

Before you start, you need:

  • An integration that is published as a private integration. This is required because you will configure OAuth in the integration’s settings in the Netlify UI.
  • An OAuth identity provider that supports and follows the OAuth 2.0 protocol. You will need access to their developer portal.
  • The authorization URL and token URL for your OAuth identity provider.

A good understanding of how OAuth works is also recommended. Learn more about OAuth 2.0.

Configure your integration for OAuth

To configure your integration to work with OAuth, you need to register a client application with your OAuth identity provider and then configure your integration for OAuth in the Netlify UI.

Register a client application with your OAuth identity provider

OAuth identity providers require you to identify what sites and services can authenticate against the authorization server. These identified sites and services are often referred to as client applications.

To begin, register Netlify’s integration service as a client application with your OAuth identity provider.

  1. Go to the developer portal of the OAuth identity provider you want to integrate with.
  2. Find the section to register a new client application.
  3. Fill in the following details:
    • Name: you can use any value here. For example, Netlify integration service
    • Redirect URI: set this to https://api.netlify.com/auth/done/identeer
    • Scopes: select the scopes you require from the identity provider
  4. After registering the client application, you will receive a client ID and client secret. Keep these safe as you will need them in the next step.

Next, configure your integration for OAuth in the Netlify UI.

Configure your integration to work with your OAuth identity provider

After you create a client application on your OAuth identity provider, you can configure your integration to work with OAuth in the Netlify UI.

You will need to provide the authorization details for your OAuth identity provider and the details for the client application you registered in the steps documented above.

  1. If you haven’t already, follow the steps to publish your integration as a private integration.
  2. In the Netlify UI, select the Integrations tab for your team and find your private integration.
  3. Select the gear icon (labeled “Settings” for screen readers) to open the settings.
  4. Under OAuth, select Configure OAuth.
  5. Fill in the details:
    • Short Description: the name of the OAuth identity provider
    • Scopes: the scopes you want to request from your identity provider
    • Authorization URL: the authorization URL for your identity provider
    • Token URL: the token URL for your identity provider
    • Client ID: the ID of the client application you registered with your identity provider
    • Client Secret: the secret for the client application you registered with your identity provider
  6. Select Save.

You can visit this section again later to edit any of the values you provided.

Now that you’ve completed this step, you can add the OAuth card element to your integration UI.

Add OAuth to your integration UI

Now that you have configured your integration to work with OAuth, you can use the OAuth card element to add an OAuth section to your integration UI. Users will complete this form to authenticate with your OAuth identity provider when they enable and configure your integration for use.

src/ui/index.ts
route.addOAuthCard({
   providerFriendlyName: "ABC OAuth Identity Provider",
   connectWithMessage: "Connect with ABC OAuth Identity Provider",
   disconnectFromMessage: "Disconnect from ABC OAuth Identity Provider",
   disconnectWarning:
      "Add this property to show a custom warning to users before they disconnect from your OAuth identity provider",
});

Configure your integration before you add the OAuth card

The OAuth card element won’t render until you have configured your integration to work with your OAuth identity provider. Once you add the configuration, the element will render locally and in previews.

Use the OAuth token in your integration

Now that you have configured your integration to use OAuth, an OAuth token is available to the integration through API Handlers.

To access the token, use providerOAuthToken on the context object that is provided to all API handlers deployed with your integration. You can use this token to make authenticated requests to your API.

src/index.ts
integration.addApiHandler("your-handler", async (event, context) => {
  const { providerOAuthToken } = context;
  // use the token to make authenticated requests to your API


  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello World" }),
  };
});

Next steps

After you add the element to your UI and add logic to use the authentication token, make sure to commit and push the update to your repository. This will kick off a new build and deploy of your integration site to ensure the latest version is available when users enable the integration.

Learn about best practices for using OAuth with your integration.