Step 1: Setup OAuth Process

Overview

To initiate the OAuth process, redirect the customer to the URL below, providing your app’s client ID, redirect URI, and any state your app needs on redirect (usually an anti-forgery token to prevent CSRF attacks).

URL to start OAuth process with Yext

// Note domain is different than API endpoints domain
https://api.yext.com/oauth2/accesstoken
        client_id=<CLIENT_ID>&
         redirect_uri=<REDIRECT_URI>&
         state=<STATE>&
         response_type=code
         grant_type=authorization_code

We recommend using a 470 x 600 pixel popup window to collect the customer’s information.

The redirect URI should:

• exactly match a domain (including subdomain) found in the list of OAuth Redirect Domains in the App configuration
• be fully URL-encoded, and
• be an absolute URI, including the protocol (https%3A%2F%2F, for example)

Permission Scopes

Permission scopes are not specified during the OAuth flow; they are configured when you create or edit your app with the Permissions and Endpoints values in the App Directory configuration.

If the customer successfully authenticates and authorizes the app, Yext will redirect the customer back to your app with:

Successful authentication/authorization redirect URL

// If your URI does not contain query parameters, appended with ?
<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>
 
// If your URI contains query parameters, appended with &
<REDIRECT_URI>&code=<AUTHORIZATION_CODE>&state=<STATE>

Your app will receive an authorization code and any state you specified. With the authorization code, your app should make a server-side HTTPS POST call to the OAuth access token endpoint with your app’s client ID, API key, authorization code, and redirect URI (used for validation, not for callback) in a standard Content-Type: application/x-www-form-urlencoded body:

Access token API endpoint

// Note domain is different than domain in URL to start OAuth process
https://api.yextapis.com/oauth2/accesstoken

POST request, exchanging authorization code for access token

POST /oauth2/accesstoken HTTP/1.1
Host: api.yextapis.com
Content-Type: application/x-www-form-urlencoded
 
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>&
code=<AUTHORIZATION_CODE>&
redirect_uri=<REDIRECT_URI>&

REDIRECT_URI

Your call to the accesstoken endpoint must exactly match the used in your initial authorize call, including domain, path, and query parameters.

If successful, you will receive an HTTP 200 response with a JSON payload containing the access token, app-specific account ID, and account name:

{
    “access_token”: “<ACCESS_TOKEN>”,
    “appSpecificAccountId”: “<APP_SPECIFIC_ACCOUNT_ID>”,
    “accountName”: “<ACCOUNT_NAME>”,
}

You can now use this access token to make calls to the Yext APIs, as well as the app-specific account ID for identifying webhook payloads. You are free to show the account name in your UI to let the customer know that they have successfully linked their Yext account.

Note

Access tokens should be stored securely (e.g., encrypted at rest), as they are analogous to customer passwords. Never expose the access token outside of a secure connection with Yext during API calls.