OAuth und Berechtigungsbereiche
Yext verwendet für die Authentifizierung und Autorisierung ein OAuth 2.0-Standard-Framework. Um das OAuth-Verfahren zu beginnen, leiten Sie den Kunden auf die nachfolgende URL und geben Sie dabei die Client-ID Ihrer App, die Weiterleitungs-URI und jeglichen Zustand an, den Ihre App im Rahmen der Umleitung benötigt (in der Regel ein Fälschungsschutz-Token zur Verhinderung von CSRF-Angriffen).

URL zum Starten des OAuth-Vorgangs mit Yext
// Beachten Sie, dass sich die Domain von der API-Endpunkte-Domain unterscheidet
https://www.yext.com/oauth2/authorize?
                            client_id=<CLIENT_ID>&
                            redirect_uri=<REDIRECT_URI>&
                            state=<STATE>&
                            response_type=code
Zur Abfrage der Informationen des Kunden empfehlen wir die Verwendung eines Pop-up-Fensters der Größe 470 x 600 Pixel.
Die Weiterleitungs-URI sollte:
  • exakt mit einer Domain (einschließlich Subdomains) aus der Liste der OAuth-Weiterleitungs-Domains in der App-Directory-Konfiguration übereinstimmen,
  • vollständig URL-codiert sein und
  • einschließlich des Protokolls eine absolute URI sein (z. B. https%3A%2F%2F).

OAuthRedirectDomains
Konfiguration für OAuth-Weiterleitungs-Domains auf der „App-Details“-Seite

BERECHTIGUNGSBEREICHE Berechtigungsbereiche werden nicht während des OAuth-Vorgangs angegeben. Sie werden konfiguriert, wenn Sie Ihre App mit den Berechtigungs- und Endpunkte-Werten in der App-Directory-Konfiguration erstellen oder bearbeiten.


Wenn der Kunde die App erfolgreich authentifiziert und autorisiert, wird ihn Yext hiermit zurück zu Ihrer App leiten:

Weiterleitungs-URL bei erfolgreicher Authentifizierung/Autorisierung
// Falls Ihre URI keine mit ? beigefügten Abfrageparameter enthält
<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>
 
// Falls Ihre URI mit & beigefügte Abfrageparameter enthält
<REDIRECT_URI>&code=<AUTHORIZATION_CODE>&state=<STATE>
Ihre App erhält einen Autorisierungscode und jeglichen von Ihnen angegebenen Zustand. Mit diesem Autorisierungscode sollte Ihre App eine serverseitige „HTTPS POST“-Anfrage an den OAuth-Zugriffstoken-Endpunkt senden und dabei die Client-ID, den API-Schlüssel, den Autorisierungscode und die Weiterleitungs-URI (für die Validierung, nicht für den Rückruf) angeben. Das Ganze in einem Standard-Inhaltstyp: application/x-www-form-urlencoded Text:

Zugriffstoken API-Endpunkt
// Beachten Sie, dass sich die Domain von der Domain in der URL zum Start des OAuth-Vorgangs unterscheidet
https://api.yext.com/oauth2/accesstoken

POST-Anforderung, Austausch des Autorisierungscodes gegen den Zugriffstoken
POST /oauth2/accesstoken HTTP/1.1
Host: api.yext.com
Inhaltstyp: 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 Ihr in Ihrer Abfrage an den Zugriffstoken-Endpunkt muss exakt mit dem übereinstimmen, der in Ihrer ursprünglichen Anfrage nach Autorisierung verwendet wurde, einschließlich Domain, Pfad und Abfrageparameter.


Im Erfolgsfall werden Sie eine „HTTP 200“-Antwort mit JSON-Nutzdaten erhalten, die den Zugriffstoken, die App-spezifische Konto-ID und den Kontonamen enthält:
{
    “access_token”: “<ACCESS_TOKEN>”,
    “appSpecificAccountId”: “<APP_SPECIFIC_ACCOUNT_ID>”,
    “accountName”: “<ACCOUNT_NAME>”,
}

Nun können Sie diesen Zugriffstoken verwenden, um die Yext-APIs aufzurufen. Mit der App-spezifischen Konto-ID können Sie zudem Webhook-Nutzdaten identifizieren. Es steht Ihnen frei, den Kontonamen in Ihrem UI anzuzeigen, um so den Nutzer wissen zu lassen, dass er sein Yext-Konto erfolgreich verknüpft hat.

Zugriffstokens sollten sicher aufbewahrt werden (z. B. im Ruhezustand verschlüsselt), da sie letztendlich analog zu Kundenpasswörtern sind. Geben Sie Zugriffstokens niemals außerhalb einer sicheren Verbindung mit Yext während API-Aufrufen preis.

Umgang mit OAuth-Fehlerfällen

Falls der Kunde die App nicht authentifiziert oder autorisiert, wird ihn Yext mit einer Fehlermeldung und einer Fehlerbeschreibung zurück zur App leiten:

Weiterleitungs-URL bei erfolgloser Authentifizierung/Autorisierung
// Falls Ihre URI keine mit ? beigefügten Abfrageparameter enthält
<REDIRECT_URI>?error=<ERROR>&error_description=<ERROR_DESCRIPTION>state=<STATE>
 
// Falls Ihre URI mit & beigefügten Abfrageparameter enthält
<REDIRECT_URI>&error=<ERROR>&error_description=<ERROR_DESCRIPTION>state=<STATE>

Die folgenden Fehler können zurückgegeben werden:
  • access_denied
    • Der Kunde hat die App nicht dazu autorisiert, mit den angefragten Berechtigungen auf die angefragten Endpunkte zuzugreifen.
  • unsupported_response_type
    • Der angegebene Antworttyp wird nicht unterstützt. Unsere OAuth unterstützt nur den Code-Antworttyp.

Verwendung von APIs mit OAuth-Zugriffstokens

Da die im Rahmen der API-Antworten bereitgestellten Yext-Konto-IDs vom Kunden einstellbar und nicht global eindeutig sind, akzeptieren die Yext-APIs für den Zugriff auf Ressourcen das me-Makro anstelle einer Konto-ID. In Verbindung mit einem OAuth-Zugriffstoken werden API-Anfragen das me-Makro zu dem zugehörigen Konto auflösen. Beispiel:
GEThttps://api.yext.com/v2/accounts/me/locations?access_token=&v=

APP-SPEZIFISCHE KONTO-ID Die App-spezifische Konto-ID kann nicht anstelle des me-Makros verwendet werden.