OAuth and Permission Scopes
Yext uses a standard OAuth 2.0 framework for authentication and authorization. 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://www.yext.com/oauth2/authorize?
                            client_id=<CLIENT_ID>&
                            redirect_uri=<REDIRECT_URI>&
                            state=<STATE>&
                            response_type=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 App Directory configuration,
  • be fully URL-encoded, and
  • be an absolute URI, including the protocol (https%3A%2F%2F, for example)

OAuthRedirectDomains
Configuration for OAuth Redirect Domains on “App Details” page

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.yext.com/oauth2/accesstoken

POST request, exchanging authorization code for access token
POST /oauth2/accesstoken HTTP/1.1
Host: api.yext.com
Content-Type: application/x-www-form-urlencoded
 
client_id=<CLIENT_ID>&
client_secret=<API_KEY>&
code=<AUTHORIZATION_CODE>&
redirect_uri=<REDIRECT_URI>&
grant_type=authorization_code
REDIRECT_URI Your in 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.

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.

Handling OAuth error cases

If the customer does not authenticate or authorize the app, Yext will redirect the customer back to the app with error and error description parameters:

Unsuccessful authentication/authorization redirect URL
// If your URI does not contain query parameters, appended with ?
<REDIRECT_URI>?error=<ERROR>&error_description=<ERROR_DESCRIPTION>state=<STATE>
 
// If your URI contains query parameters, appended with &
<REDIRECT_URI>&error=<ERROR>&error_description=<ERROR_DESCRIPTION>state=<STATE>

The following errors can be returned:
  • access_denied
    • The customer did not authorize the App to access the requested endpoints with the requested permissions.
  • unsupported_response_type
    • The specified response type is unsupported. Our OAuth only supports the code response type.

Using APIs with OAuth access tokens

Since Yext account IDs provided in API responses are customer-settable and not unique globally, the Yext APIs accept the me macro in the place of an account ID to access resources. Used in conjunction with an OAuth access token, API requests will resolve the me macro to the associated account. For example:
GEThttps://api.yext.com/v2/accounts/me/locations?access_token=&v=

APP-SPECIFIC ACCOUNT ID The app-specific account ID cannot be used in place of the me macro.