Graph Authentication

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.

Graph Authentication is the part of Netlify Graph that simplifies API authentication and token management. It removes the friction of re-writing authentication code to connect to third-party APIs.

When you connect to an API provider, you can use the authentication tokens from the provider in your site builds and Netlify Functions. Graph Authentication handles token refresh and scope management on your behalf.

# Access scopes

When connecting to an API or service with Graph Authentication, you can define scopes for the automatically-generated token.

To define access scopes

  1. In Netlify Graph, select your site, then navigate to the Graph page.
  2. On the left side of Graph Explorer, find a service you want to integrate with from the list of services, then select Authentication.
  3. Choose your scopes, then select Enable.
  4. Follow the authentication flow for the selected API provider.

Graph can’t proxy credentials

In the current release, you can only log in with your own credentials and can’t proxy site visitor credentials. For example, you can’t prompt the visitor of your website to log in with a provider.

# Authentication tokens

Authentication tokens are specific to each site. If you enable an API provider for a site, you can’t reuse the token on other sites within your team. You need to authenticate with the same provider again for every site.

Protect your token

The ONEGRAPH_AUTHLIFY_TOKEN token is generated for your site when you enable Graph Authentication. It gives direct access to all service tokens associated with the site. Ensure that only authorized parties can use it. Additional security measures are in development to reduce the Time To Live (TTL) for tokens in builds and functions.

When services are authenticated, Graph Authentication automatically handles OAuth flows and token refresh for you.

# Basic secret handling

You need to use the @netlify/functions package to access API tokens.

In your Netlify Function, you can access secrets with NetlifySecrets and getSecrets(). The getSecrets() function returns a JSON blob that contains all token information associated with a given site.

For example, if you authenticated with the Spotify API in the Netlify UI, you can verify that you are logged in by using code like this:

import { Handler, getSecrets, NetlifySecrets } from "@netlify/functions";

const handler: Handler = async (event, context) => {
  let secrets: NetlifySecrets = {};
  secrets = await getSecrets(event);

  if (secrets.spotify)
  {
    return {
      statusCode: 200,
      body: JSON.stringify({ready: secrets.spotify.isLoggedIn}),
    }
  }
  else
  {
    return {
      statusCode: 200,
      body: JSON.stringify({message: "Could not get Spotify information."}),
    }
  }
};

export { handler };

In the example above, secrets becomes the JSON blob that contains tokens to every service you’ve authenticated for your site.

Assuming that you save the file as checkStatus.ts in your functions directory, you can verify the results by sending a GET request to this URL:

https://YOUR_SITE.netlify.app/.netlify/functions/checkStatus

You should get a result similar to this if you’ve authenticated with Spotify:

Screenshot of Postman with an example response from a Netlify function.

You can get the bearer token by passing <YOUR_API_PROVIDER>.bearerToken to the native SDK you are using, such as the Spotify web API wrapper or Octokit libraries from GitHub.

If you are interested in an end-to-end demo solution that uses GitHub with Graph Authentication, refer to the gravity demo.

# Supported API providers

For the Beta release, we support authenticating with the following providers:

  • Box
  • Cloudinary
  • Contentful
  • GitHub
  • npm
  • Salesforce
  • Sanity
  • Spotify
  • Stripe

If you’re looking for a provider not currently listed here, send us your feedback.

# Custom clients

Netlify Graph supports using external OAuth clients for supported services. Make sure you have the client ID and client secret from the third-party service that provides the OAuth client you want to use.

To use a custom OAuth client

  1. In Netlify Graph, select your site, then navigate to the Graph tab.
  2. On the left side of Graph Explorer, find a service you want to integrate with from the list of services, then select Authentication.
  3. Select Set custom OAuth client.
  4. Enter your custom client’s ID and secret, then select Save.

When configuring the custom client, you need to set the callback URL in the third-party OAuth service to:

https://graph.netlify.com/oauth/receive

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.