Yext uses a standard OAuth 2.0 framework for authentication and authorization. This article walks through how to initiate the OAuth process, redirect the customer, and authenticate and authorize the user.

Start the OAuth Process

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).

// Note: this domain differs from the API endpoints domain
https://www.yext.com/oauth2/authorize
        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 pop-up window to collect the customer's information.

The redirect URI must:

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

Permission Scopes

Permission scopes aren't specified during the OAuth flow. Configure them when you create or edit your app, using the Permissions and Endpoints values in the App Directory configuration.

If the customer successfully authenticates and authorizes the app, Yext redirects the customer back to your app with an authorization code:

// If your URI doesn't contain query parameters, append with ?
<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>

// If your URI contains query parameters, append with &
<REDIRECT_URI>&code=<AUTHORIZATION_CODE>&state=<STATE>

Your app receives an authorization code and any state you specified. With the authorization code, make a server-side HTTPS POST call from your app to the OAuth access token endpoint, including 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:

// Note: this domain differs from the domain used to start the OAuth process
https://api.yextapis.com/oauth2/accesstoken

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>&
grant_type=authorization_code

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

If successful, you 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>"
}

Use this access token to make calls to the Yext APIs, and use the app-specific account ID to identify webhook payloads. You can show the account name in your UI to let the customer know they've successfully linked their Yext account.

Note: Store access tokens securely, such as encrypted at rest, since they're equivalent to customer passwords. Never expose an access token outside a secure connection with Yext during API calls.

Handle OAuth Error Cases

If the user doesn't authenticate or authorize the app, Yext redirects them back to the app with error and error description parameters:

// If your URI doesn't contain query parameters, append with ?
<REDIRECT_URI>?error=<ERROR>&error_description=<ERROR_DESCRIPTION>&state=<STATE>

// If your URI contains query parameters, append with &
<REDIRECT_URI>&error=<ERROR>&error_description=<ERROR_DESCRIPTION>&state=<STATE>

Yext can return the following errors:

Use APIs with OAuth Access Tokens

Yext account IDs returned in API responses are customer-settable and aren't unique globally. To account for this, Yext APIs accept the me macro in place of an account ID. Used together with an OAuth access token, API requests resolve the me macro to the associated account. For example:

GET https://api.yextapis.com/v2/accounts/me/locations?access_token=<ACCESS_TOKEN>&v=<VERSION>

Note: You can't use the app-specific account ID in place of the me macro.