A sERPa API-ban háromféle hitelesítést használhatunk:
•Név - Jelszó (Basic)
•Cserekulcs (API Key)
•Token (Bearer token, JSON Web Token, JWT)
A hitelesítési módot az Interfész definíció Általános fülén a Hitelesítés mezőben lehet kiválasztani:
Mindhárom hitelesítés használható mindkét működési módban, tehát akkor is, ha a sERPa a szolgáltató, és akkor is, ha Külső rendszer a szolgáltató:
Ha a sERPa a szolgáltató, akkor a hitelesítő adatokat a hívó fűzi hozzá a kérésekhez, és a sERPa API ellenőrzi azokat, míg ha Külső rendszer a szolgáltató, akkor a Külső rendszer használatához szükséges hitelesítő adatokat a sERPa API fűzi hozzá a kérésekhez.
Fontos tudni, hogy a sERPa API-ban több interfészt (több API-t) definiálhatunk, és minden interfészhez (minden API-hoz) saját hitelesítési módot, saját azonosítókat vehetünk fel. Az egyik interfészünk lehet mondjuk Basic hitelesítésű, míg a másik lehet API Key. Vagy lehet mindegyik API Key, de mindegyikben más lehet a Cserekulcs (az API Key) értéke. Megadhatjuk azt is, hogy az adott interfészen keresztül milyen adatokhoz lehet hozzáférni. Ezekkel az eszközökkel teljesen egyedi, személyre szabott API-kat alakíthatunk ki, így mindenki csak azokhoz az adatokhoz férhet hozzá, amihez jogot adtunk neki. Ha egy interfész (egy API) kompromittálódik, akkor sem lehet hozzáférni a sERPában tárolt összes adathoz, csak azokhoz, amelyeket az adott interfészen keresztül szolgáltatunk.
Név - Jelszó (Basic) hitelesítés
Szabványos Basic hitelesítés.
Ha a sERPa a szolgáltató, akkor minden API hívás fejlécében vár egy "Authorization" elemet, melynek értéke: "Basic <credentials>", ahol "<credentials>" a sERPában megadott Azonosító és Jelszó, kettősponttal elválasztva, Base64 kódolásban.
A hozzáférési adatokat (Azonosító és Jelszó) osszuk meg a hívóval. A hozzáférési adatok nem járnak le, tehát mindaddig használhatók, amíg a sERPában meg nem változtatjuk, vagy nem töröljük azokat.
Ha Külső rendszer a szolgáltató, akkor a sERPa API minden API hívás fejlécéhez hozzáfűz egy "Authorization" elemet, melynek értéke: "Basic <credentials>", ahol "<credentials>" a sERPában megadott Azonosító és Jelszó, kettősponttal elválasztva, Base64 kódolásban.
A hozzáférési adatokat (Azonosító és Jelszó) a Külső rendszer üzemeltetőjétől kapjuk. Ha a Külső rendszer üzemeltetője megváltoztatja a hozzáférési adatokat, akkor azokat nekünk is újra meg kell adni a sERPában az interfész definíciójában.
Cserekulcs (API Key) hitelesítés
Szabványos API Key hitelesítés.
A fenti képen a Cserekulcs egy GUID, ez nem kötelező, a Cserekulcs bármi lehet.
Ha a sERPa a szolgáltató, akkor minden API hívás fejlécében vár egy "X-API-Key" elemet, melynek értéke a sERPában megadott Cserekulcs.
A Cserekulcsot osszuk meg a hívóval. A Cserekulcs nem jár le, tehát mindaddig használható, amíg a sERPában meg nem változtatjuk, vagy nem töröljük.
Ha Külső rendszer a szolgáltató, akkor a sERPa API minden API hívás fejlécéhez hozzáfűz egy "X-API-Key" elemet, melynek értéke a sERPában megadott Cserekulcs.
A Cserekulcsot a Külső rendszer üzemeltetőjétől kapjuk. Ha a Külső rendszer üzemeltetője megváltoztatja a Cserekulcsot, akkor azt nekünk is újra meg kell adni a sERPában az interfész definíciójában.
Token (Bearer token, JSON Web Token, JWT) hitelesítés
Szabványos Bearer token hitelesítés.
Ha a sERPa a szolgáltató, akkor az első API hívás előtt kérni kell a sERPa API-tól egy tokent, majd ezt a tokent kell minden API hívás fejlécében egy "Authorization" elemben visszaküldeni, melynek értéke: "Bearer <token>", ahol "<token>" a sERPa API-tól kapott token.
A tokenkérés menete: egy POST hívást kell indítani a sERPában megadott Hitelesítés URL-re (POST https://cégem.hu/serpaapi/interfészURL/hitelesítésURL), a kérés body-jában kell megadni a felhasználónevet és jelszót, amit a sERPában rögzítettünk:
{
"username": "string",
"password": "string"
}
Sikeres autentikáció esetén 200 OK választ kapunk, a body:
{
"token": "string"
}
A kérés, illetve a válasz body adatformátuma megegyezik a sERPában megadott interfész adatformátummal, a fenti példákban JSON.
A kibocsátott JSON Web Token egy napig érvényes. Egy nap után az API kérések 401 Unauthorized választ fognak adni, ekkor a hívónak kérni kell egy új tokent.
A hozzáférési adatokat (Azonosító, Jelszó, Hitelesítés URL) osszuk meg a hívóval. A hitelesítési adatok nem járnak le, tehát mindaddig használhatók újabb tokenek kérésére, amíg a sERPában meg nem változtatjuk, vagy nem töröljük azokat.
Ha Külső rendszer a szolgáltató, akkor a sERPa az első API kérés előtt kér egy tokent a Külső szolgáltatótól, majd minden API hívás fejlécéhez hozzáfűz egy "Authorization" elemet, melynek értéke: "Bearer <token>", ahol "<token>" a Külső szolgáltatótól megkapott token.
A token kérés menete megegyezik a sERPa a szolgáltató részben leírtakkal, csak természetesen a sERPa API küldi a hitelesítés URL-re a hitelesítési adatokat, és várja a tokent.
A megkapott token bármi lehet, nem kötelező, hogy JSON Web Token legyen. Amit megkap a sERPa API, azt fogja visszaküldeni a kérések fejlécében.
Jelenleg a sERPa API nem tudja megújítani a tokent, ezért ha a token lejár, a sERPa API nem fog tudni kommunikálni a Külső rendszerrel. Megoldás lehet az, hogy a Külső rendszer egy napig érvényes tokent bocsát ki, és a sERPa API-t minden nap újraindítjuk.
A hozzáférési adatokat (Azonosító, Jelszó, Hitelesítés URL) a Külső rendszer üzemeltetőjétől kapjuk. Ha a Külső rendszer üzemeltetője megváltoztatja a hozzáférési adatokat, akkor azokat nekünk is újra meg kell adni a sERPában az interfész definíciójában.
Sikertelen azonosítás
Sikertelen azonosítás, illetve sikertelen tokenkérés esetén 401 Unauthorized hibát kapunk, a válasz fejlécében egy "WWW-Authenticate" elemmel, melynek értéke az autentikáció típusa ("Basic", "X-API-Key", "Bearer").
