Authentifizierung
Die Rently API verwendet OAuth2 mit Bearer-Tokens. Der Ablauf ist einfach: Sie fordern mit Ihren Zugangsdaten ein Token an, speichern es und senden es im Header Authorization jeder Anfrage. Dieser Leitfaden behandelt, wie Sie das Token erhalten, wie Sie es verwenden, seinen Ablauf und die Beziehung zwischen Token und Mandant.
Das Modell in einem Satz
- Sie senden
POST /auth/tokenmit Ihren Zugangsdaten und erhalten einaccess_token. - Sie senden dieses Token im Header
Authorization: Bearer {token}bei jedem Aufruf von/api/.... - Das Token ist an Ihren Mandanten (Ihren Host) gebunden und läuft nach einem Tag ab (
expires_in≈ 86399 Sekunden).
Ihre client_id ist Ihr Benutzer bei Rently und Ihr client_secret ist Ihr Schlüssel. Falls Sie noch keinen für die API freigeschalteten Benutzer haben, wenden Sie sich an Ihren Rently-Administrator.
Das Token anfordern
Der Token-Endpunkt liegt auf dem Host Ihres Mandanten und wird mit grant_type=client_credentials aufgerufen. Der Body wird als application/x-www-form-urlencoded gesendet.
curl -X POST https://{tenant}.rently.com.ar/auth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id={username}" \
-d "client_secret={password}"
Sie können diesen Endpunkt interaktiv testen – füllen Sie client_id, client_secret und den Host Ihres Mandanten aus und senden Sie die Anfrage – in der Reference: Ein Zugriffstoken abrufen.
https://{tenant}.rently.com.ar dient als Beispiel. In der Produktion müssen Sie sowohl den Token-Endpunkt als auch die Geschäftsaufrufe auf den Host Ihres Mandanten richten. Der Host identifiziert den Mandanten: Das ausgestellte Token ist an diesen Mandanten gebunden. Das Token gegen den Host eines anderen Mandanten zu verwenden, schlägt bei der Validierung fehl (siehe Rolle des Mandanten).
Body-Parameter
| Feld | Wert | Beschreibung |
|---|---|---|
grant_type | client_credentials | Fester Wert. Es ist der Ablauf, den API-Clients verwenden. |
client_id | Ihr Benutzer | Für die API freigeschalteter Rently-Benutzer. |
client_secret | Ihr Schlüssel | Schlüssel des Benutzers. |
Antwort
Sind die Zugangsdaten gültig, erhalten Sie ein JSON mit dem Token:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiAi...",
"token_type": "bearer",
"expires_in": 86399
}
| Feld | Typ | Beschreibung |
|---|---|---|
access_token | string | Das bei jeder Anfrage zu sendende Token. |
token_type | string | Autorisierungsschema. Immer bearer. |
expires_in | number | Sekunden bis zum Ablauf (≈ 1 Tag). |
Speichern Sie das access_token und verwenden Sie es bei allen Ihren Aufrufen wieder, bis es abläuft. Fordern Sie nicht bei jeder Anfrage ein neues Token an: Das Token ist den ganzen Tag gültig.
Das Bearer-Token verwenden
Bei jedem API-Aufruf senden Sie das Token im Header Authorization mit dem Schema Bearer:
Authorization: Bearer {access_token}
Beispiel einer authentifizierten Anfrage gegen einen echten API-Endpunkt. GET /api/branchoffices listet die aktiven Filialen auf:
curl -X GET "https://{tenant}.rently.com.ar/api/branchoffices?language=es-AR" \
-H "Authorization: Bearer {access_token}"
Der Query-Parameter ?language= steuert die Sprache der Antwort (zum Beispiel ?language=es-AR). Lassen Sie ihn weg, wird die Standardsprache Ihres Mandanten verwendet. Akzeptiert wird sowohl die vollständige Kultur (es-AR) als auch der zweistellige Code (es).
Alle Geschäfts-Endpunkte (/api/...) erfordern diesen Header. Die Details jeder Operation, ihre Parameter und ihre Antworten finden Sie in der API Reference →.
Ablauf und Erneuerung
Das Token läuft etwa einen Tag nach Ausstellung ab (expires_in ≈ 86399 Sekunden). Es gibt keinen Refresh-Token-Mechanismus: Wenn das Token abläuft, fordern Sie einfach ein neues an, indem Sie das POST /auth/token mit Ihren Zugangsdaten wiederholen.
Senden Sie ein abgelaufenes, fehlendes oder ungültiges Token, antwortet die API mit 401 Unauthorized und einem Header WWW-Authenticate, der auf den Token-Endpunkt Ihres Mandanten verweist:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri=https://{tenant-host}/auth/token, resource_id=https://{tenant-host}/api
Speichern Sie Datum/Uhrzeit, zu der Sie das Token angefordert haben, und erneuern Sie es proaktiv, bevor expires_in erreicht ist. Als reaktive Alternative fordern Sie bei einem 401 das Token erneut an und wiederholen die Anfrage.
Rolle des Mandanten
Der Mandant wird aus dem Host der URL ermittelt. Wenn Sie ein Token erhalten, wird der zu diesem Host gehörende Mandant als Claim in das Token eingebettet.
Bei jedem Geschäftsaufruf prüft die API zwei Dinge:
- Dass das Token gültig und nicht abgelaufen ist.
- Dass der Mandant des Tokens mit dem Mandanten des Hosts der Anfrage übereinstimmt.
Ein für einen Mandanten ausgestelltes Token funktioniert nicht für einen anderen. Verwenden Sie ein Token gegen den Host eines anderen Mandanten, schlägt die Validierung mit 401 fehl. Fordern Sie das Token immer auf demselben Host an, auf dem Sie die Geschäftsaufrufe machen.
Außerdem sind das Ausstellen des Tokens und die Autorisierung jedes Endpunkts getrennte Ebenen: Der Benutzer muss für die Nutzung der API freigeschaltet sein, und anschließend wendet jede Operation ihre eigenen Berechtigungen an. Hat Ihr Benutzer keine Berechtigung für einen Endpunkt, kann die Anfrage abgelehnt werden, selbst wenn das Token gültig ist.
Zusammenfassung
- Token:
POST /auth/tokenmitgrant_type=client_credentials,client_id(Benutzer) undclient_secret(Schlüssel), alsapplication/x-www-form-urlencoded, gegen den Host Ihres Mandanten. - Antwort:
access_token,token_type: "bearer",expires_in(≈ 1 Tag). - Verwendung: Header
Authorization: Bearer {access_token}bei jedem Aufruf von/api/.... - Ablauf: ≈ 1 Tag, ohne Refresh-Token; fordern Sie nach Ablauf ein neues Token an.
- Mandant: Das Token ist an den Host/Mandanten gebunden, gegen den Sie es angefordert haben; verwenden Sie es nicht gegen einen anderen Mandanten.
Mit dem Token in der Hand erkunden Sie die Endpunkte weiter in der API Reference →.