Zum Hauptinhalt springen

Plattform-API-Authentifizierung (JWT)

Die vitalera REST API verwendet JWT (JSON Web Token)-Authentifizierung basierend auf dem OAuth 2.0-Standard.

Zugangsdaten erhalten​

Kontaktieren Sie support@vitalera.io, um Folgendes anzufordern:

  • Client ID — identifiziert Ihre Anwendung
  • Client Secret — authentifiziert Ihre Anwendung
  • Application ID — wird fuer die Zugangsdatenrotation verwendet

Client Credentials Grant​

Fuer Server-zu-Server (Machine-to-Machine)-Integrationen:

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credentials",
           "client_id": "<CLIENT_ID>",
           "client_secret": "<CLIENT_SECRET>"
         }'

Antwort:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Password Grant​

Fuer Benutzer-Login-Flows (z. B. mobile oder Web-Apps, die einzelne Benutzer authentifizieren):

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "password",
           "username": "<USERNAME>",
           "password": "<PASSWORD>"
         }'

Antwort:

{
  "id_token": "<ID_TOKEN>",
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "sub": "<USER_ID>"
}

API-Anfragen ausfuehren​

Fuegen Sie das Access Token in den Authorization-Header jeder Anfrage ein:

curl -X GET "https://api.vitalera.io/api/plans/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Token-Gueltigkeit​

Access Tokens sind 1 Stunde (3600 Sekunden) gueltig. Wenn ein Token ablaeuft, gibt die API HTTP 401 Unauthorized zurueck:

{
  "errors": [
    {
      "errorType": "expired_token",
      "message": "Access token expired"
    }
  ]
}

Token-Aktualisierung​

Wenn Sie ein Refresh Token (ueber Password Grant) erhalten haben, koennen Sie Ihr Access Token ohne erneute Authentifizierung aktualisieren:

curl -X POST "https://api.vitalera.io/api/auth/tokens/refresh/" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
           "refresh_token": "<REFRESH_TOKEN>"
         }'

Token-Validierung​

Ueberpruefen Sie, ob ein Token noch gueltig ist:

curl -X GET "https://api.vitalera.io/api/auth/tokens/validate/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Zugangsdatenrotation​

Rotieren Sie aus Sicherheitsgruenden regelmaessig Ihre Client-Zugangsdaten. Dies erfordert ein gueltiges JWT und die application_id:

curl -X POST "https://api.vitalera.io/api/applications/rotate_credentials/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "application_id": "<APPLICATION_ID>"
         }'

Antwort:

{
  "id": "<APPLICATION_ID>",
  "name": "TestApp",
  "organization": "123",
  "client_id": "<NEW_CLIENT_ID>",
  "client_secret": "<NEW_CLIENT_SECRET>",
  "application_types": ["API"]
}

Nach der Rotation werden die vorherigen Zugangsdaten sofort ungueltig.

Brauchen Sie Hilfe?​

Kontaktieren Sie support@vitalera.io fuer Unterstuetzung bei der Authentifizierungseinrichtung.