Authentifizierung

Jeder API-Request erfordert eine entsprechende Authentifizierung. Für die Identifikation des Clientsystems, das auf die ONE API zugreift, werden JSON Web Tokens (JWT) eingesetzt.

Voraussetzung für die Anforderung eines JWT ist ein API-Schlüssel (Key). Jeder immonex-ONE-Partner erhält einen oder mehrere API-Keys.

Partner-API-Keys ermöglichen die Nutzung diverser API-Funktionen sowie den Zugriff auf sensible Informationen. Sie dürfen daher ausschließlich in gesicherten Umgebungen gespeichert und verwendet werden. Eine Nutzung in öffentlich zugänglichen Systemen wie Web-Apps oder Repositories ist nicht erlaubt.

Mit jedem API-Key ist ein Nutzerprofil mit individuellen Berechtigungen und Vorgaben für die Verarbeitung der API-Anfragen verknüpft. Dieses Konstrukt wird als Provider bezeichnet.

Ein JWT kann ab dem Zeitpunkt der Anforderung 24 Stunden lang für den Zugriff auf die ONE API verwendet werden.

Wie bereits erwähnt, unterscheidet sich der Namensraum (Namespace) der Authentifizierungs-REST-Requests von denen der regulären API-Anfragen, die Basis-URL lautet hier:

https://api.immonex.one/wp-json/jwt-auth/v1

Nach erfolgreicher Anforderung erfolgt die Übermittlung des JWT bei allen folgenden API-Requests als Bearer-Token im HTTP-Header Authorization:

Authorization: Bearer JSON_WEB_TOKEN

Token anfordern

Request
POST https://api.immonex.one/wp-json/jwt-auth/v1/token

1
2
3

{
	"api_key": "PROVIDER API KEY"
}

Response (Erfolg)
200 OK

1
2
3
4

{
	"token": "JSON_WEB_TOKEN",
	"provider": "Name des zugehörigen Providers"
}

Response (Fehler)
403 Forbidden

1
2
3
4
5
6
7

{
    "code": "[jwt_auth] invalid_api_key",
    "message": "Der angegebene API-Schlüssel gehört nicht zu einem gültigen Benutzer.",
    "data": {
        "status": 403
    }
}

Token validieren

Request
POST https://api.immonex.one/wp-json/jwt-auth/v1/token/validate

Response (Token gültig)
200 OK

1
2
3
4
5
6

{
    "code": "jwt_auth_valid_token",
    "data": {
        "status": 200
    }
}

Response (Token ungültig)
403 Forbidden

1
2
3
4
5
6
7

{
    "code": "jwt_auth_invalid_token",
    "message": "Expired token",
    "data": {
        "status": 403
    }
}