​
Introduction

There are two methods that can be used to authenticate with @zapier/ai-actions:

  • API Key: If you plan on only using the AI Actions client to interact with AI Actions on your behalf
  • OAuth: If you plan on creating an OAuth app to allow users to interact with AI Actions on their behalf

​
API Key

Your API key can be retrieved from the Credentials page.

Treat your API key like a password.

It can be used to run your AI Actions.

For example: if you set up a “Gmail: Find email” action, anyone with your API key can read all your email.

Create an AiActions client with the API key:

import { AiActions } from "@zapier/ai-actions";

const client = new AiActions({
  auth: {
    apiKey: "YOUR_API_KEY",
  },
});

​
OAuth

​
Creating an OAuth app

Click here to create an OAuth app

Click here to create a new OAuth app to use for authenticating with AI Actions.

In order to work with the API client, your app must have “Public Client” checked.

​
Getting an OAuth token

​
Creating the AiActionsAuth object

@zapier/ai-actions provides a helper class to handle the auth process.

This is done with the AiActionsAuth class:

import { AiActionsAuth } from "@zapier/ai-actions";

const aiActionsAuth = new AiActionsAuth({
  clientId: "YOU_APP_CLIENT_ID",
  redirectUri: "YOUR_APP_REDIRECT_URI",
});

​
Storing the code verifier securely

@zapier/ai-actions uses the OAuth 2.0 PKCE flow to facilitate the OAuth process. As part of this, a “code verifier” is generated.

By default, AiActionsAuth will store the verifier in the browser’s localStorage.

This is not recommended for production use since it can be easily accessed by malicious scripts, and it will not work server-side.

To facilitate storing the code verifier securely, the constructor for AiActionsAuth has options that can be used.

import { AiActionsAuth } from "@zapier/ai-actions";

const aiActionsAuth = new AiActionsAuth({
  clientId: "YOU_APP_CLIENT_ID",
  redirectUri: "YOUR_APP_REDIRECT_URI",
  async storeVerifier(verifier) {
    // store the verifier somewhere secure for your user (i.e. database or KV store)
  },
  async getVerifier(): Promise<string> {
    // this function MUST return the verifier stored for the user by `storeVerifier`
    // each verifier can only be used once, and it must be consistend throughout the OAuth flow
  },
});

​
Generating the authorization OR quick account creation URL

Once you have an AiActionsAuth object, you can use it to generate the authorization URL:

const authUrl = await aiActionsAuth.generateAuthUrl();

// ...

<a href={authUrl}>Authenticate with AI Actions</a>;

This URL can be used to redirect the user to the authorization page. Once the user has authorized your app, they will be redirected to the redirectUri you provided.

You can also generate a quick account creation URL. This will ensure that the user has a Zapier account before authorizing your app.

If they do not have a Zapier account, one will be created for them. If they already have a Zapier account, they will be asked to log in on zapier.com.

const quickAccountCreationUrl = await aiActionsAuth.generateCreateAccountUrl(
  "Firstname",
  "Lastname",
  "user@example.com"
);

// ...

<a href={quickAccountCreationUrl}>Authenticate with AI Actions</a>;

After going through this flow, they will end up back on the redirectUri that you provided.

​
Getting an access token

After authorizing your app, the user will be redirected to the redirectUri you provided along with a code query parameter.

This code can now be used to get an access token

import { AiActions } from "@zapier/ai-actions";

// `code` will be in the query params; get it however you like (most likely server-side)
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get("code");

// this access token can now be used to generate an AiActions client
const oauthToken = await aiActionsAuth.getToken(code);

const aiActionsClient = new AiActions({
  auth: {
    token: oauthToken.access_token,
  },
});

try {
  // this will pass if auth succeeds, or throw an error if it fails
  await aiActionsClient.checkAuth();
} catch (e) {
  console.error("Error checking AI Actions auth", e);
}

​
Refreshing the access token

Access tokens expire after a certain amount of time. To refresh the token, you can use the refreshToken method along with the refresh_token:

import {
  OAuthAccessToken,
  refreshOAuthToken,
  tokenNeedsRefresh,
} from "@zapier/ai-actions";

// get the stored token for the current user; `getAiActionsToken` is a placeholder for your own function
const oauthToken: OAuthAccessToken = await getAiActionsToken();

if (tokenNeedsRefresh(oauthToken)) {
  const refreshed = await refreshOAuthToken({
    clientId: "YOUR_CLIENT_ID",
    refreshToken: oauthToken.refresh_token,
  });

  if (refreshed) {
    // `setAiActionsToken` is a placeholder for your own function
    await setAiActionsToken(refreshed);
  }
}
Getting startedUsage examples