API Authentication

Documentation (English)

For the German version, please scroll down to “Dokumentation (Deutsch)”

How do I authenticate my requests?

To ensure secure access to the Enterprise API, we utilize a combination of OAuth2 and subscription keys.

These mechanisms work together to authenticate and authorize API requests, safeguarding your data and ensuring that only authorized users can access the API.

OAuth2 Authentication

Each customer is provided with unique credentials, including a client ID (sent by E-mail) and client secret (sent by SMS), upon onboarding.
To authenticate, clients must first obtain an access token by making a request to our token endpoint using their credentials.
This access token is then included in the Authorization header (Authorization: Bearer <access_token>) of each API request.
The token is only valid for 5 minutes, after which it expires and must be requested again.

Subscription Key

In addition to the token, a subscription key is required to authorize access to specific API resources.
The subscription key, which is issued during the onboarding process and sent by onboarding E-mail, must be included in the Ocp-Apim-Subscription-Key header of each API request.
This key helps us manage and monitor API usage, ensuring that requests are coming from valid and authorized subscriptions.
Subscriptions are issued only once and do not expire

Security Note

Ensure that both your credentials and subscription key are stored securely and not exposed in client-side code.

How do I obtain an token?

To obtain a token, follow these steps:

Make a POST request to the token endpoint using your client credentials.

Token endpoint: https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token

Include the following parameters in the request body:

grant_type: client_credentials

client_id: Your client ID (sent by E-Mail)

client_secret: Your client secret (sent by SMS)

scope: openId

Example Token Request:

curl -v -X POST https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials' \
      -d 'client_id=[Your Unique client_id]' \
      -d 'client_secret=[Your Unique client_secret]' \
      -d 'scope=openid'

Receive the Token:

If your request is successful, you will receive a response containing the access token, which typically looks like this:

{
    "access_token": "<<CONTENT_OF_THE_JWT_TOKEN>>"
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "id_token": "<<CONTENT_OF_THE_ID_TOKEN>>"
    "not-before-policy": 0,
    "scope": "openid"
}

The access_token value is what you will use to authenticate your API requests.

Use the Token:

Include the access token in the Authorization header of your API requests.

Example API Request:

curl -v -X POST https://api.dkv-mobility.com/e-api/v2.0.0/transactions/transactionDate?size=100&page=0&customerId=0000123456&endDate=2024-05-30&startDate=2024-05-01\
     -H 'Authorization: bearer <<CONTENT_OF_THE_JWT_TOKEN>>'\
     -H 'Content-Type: application/json' \
     -H 'Content-Length: 0' \
     -H 'ocp-apim-subscription-key: <<CONTENT_OF_THE_SUBSCRIPTION_KEY>>'

Handle Token Expiry:

Tokens have an expiration time (expires_in), so you need to handle token renewal or re-authentication as needed.

Troubleshooting OAuth2 Errors

Verify Endpoint URL

Ensure you’re using the correct URL for the token endpoint. Check the API documentation for the precise endpoint and make sure there are no typos.

Check Request Headers

Make sure that the Content-Type header is set correctly to application/x-www-form-urlencoded.

Validate Credentials

Double-check that the client_id and client_secret you’re using are correct and active.

These values are case-sensitive and must match exactly what was provided during onboarding.Otherwise the authorization server denied the request

Review the error message returned by the server.

Common issues include:

Invalid Grant Type: Ensure grant_type is set to client_credentials.

Invalid Client ID/Secret: Verify the correctness of your credentials.

Missing or Invalid Parameters: Ensure all required parameters are included.

The authorization server could be temporarily unable to handle the request due to maintenance or other issues.

If the issue persists, contact the API Management Support team with detailed error information for assistance: api-management@dkv-mobility.com

Dokumentation (Deutsch)

Hier finden Sie die deutsche Dokumentation.

Enterprise API-Authentifizierung

Wie authentifiziere ich meine Anfragen?

Um einen sicheren Zugriff auf die Enterprise API zu gewährleisten, nutzen wir eine Kombination aus OAuth2 und Abonnementschlüsseln.

Diese Mechanismen arbeiten zusammen, um API-Anfragen zu authentifizieren und zu autorisieren, Ihre Daten zu schützen und sicherzustellen, dass nur autorisierte Benutzer auf die API zugreifen können.

OAuth2-Authentifizierung

Jeder Kunde erhält beim Onboarding eindeutige Zugangsdaten, einschließlich Client-ID (per E-Mail gesendet) und Client-Secret (per SMS gesendet).
Um sich zu authentifizieren, müssen sich die Kunden zunächst ein Zugriffstoken beschaffen, indem sie eine Anfrage an unseren Token-Endpunkt mit ihren Zugangsdaten stellen.
Dieses Zugriffstoken wird dann in den Authorization-Header (Authorization: Bearer <access_token>) jeder API-Anfrage eingefügt.
Das Token ist nur 5 Minuten gültig, danach läuft es ab und muss erneut angefordert werden.

Abonnementschlüssel (Subscription Key)

Zusätzlich zum Token ist ein Abonnementschlüssel (Subscription Key) erforderlich, um den Zugriff auf bestimmte API-Ressourcen zu autorisieren.
Der Abonnementschlüssel, der während des Onboarding-Prozesses ausgestellt und per Onboarding-E-Mail gesendet wird, muss ein header ocp-apim-subscription-key jeder API-Anfrage eingefügt werden.
Dieser Schlüssel hilft uns, die API-Nutzung zu verwalten und zu überwachen und sicherzustellen, dass Anfragen von gültigen und autorisierten Abonnements stammen.
Abonnementschlüssel wird nur einmal ausgegeben und läuft nicht ab.

Sicherheitshinweis

Stellen Sie sicher, dass sowohl Ihre Zugangsdaten als auch der Abonnementschlüssel sicher aufbewahrt und nicht im clientseitigen Code offengelegt werden.

Wie erhalte ich ein Token?

Um ein Token zu erhalten, befolgen Sie diese Schritte:

Senden Sie eine POST-Anfrage an den Token-Endpunkt unter Verwendung Ihrer Client-Zugangsdaten.

Token-Endpunkt: https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token

Fügen Sie die folgenden Parameter in den Anfragetext ein:

grant_type: client_credentials

client_id: Your client ID (sent by E-Mail)

client_secret: Your client secret (sent by SMS)

scope: openId

Beispiel für eine Token-Anfrage:

curl -v -X POST https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials' \
      -d 'client_id=[Your Unique client_id]' \
      -d 'client_secret=[Your Unique client_secret]' \
      -d 'scope=openid'

Token empfangen:

Wenn Ihre Anfrage erfolgreich war, erhalten Sie eine Antwort mit dem Zugriffstoken, das typischerweise so aussieht:

{
    "access_token": "<<CONTENT_OF_THE_JWT_TOKEN>>"
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "id_token": "<<CONTENT_OF_THE_ID_TOKEN>>"
    "not-before-policy": 0,
    "scope": "openid"
}

Der access_token-Wert ist das, was Sie zur Authentifizierung Ihrer API-Anfragen verwenden.

Token verwenden:

Fügen Sie das Zugriffstoken in den Authorization-Header Ihrer API-Anfragen ein.

Beispiel für eine API-Anfrage:

curl -v -X POST https://api.dkv-mobility.com/e-api/v2.0.0/transactions/transactionDate?size=100&page=0&customerId=0000123456&endDate=2024-05-30&startDate=2024-05-01\
     -H 'Authorization: bearer <<CONTENT_OF_THE_JWT_TOKEN>>'\
     -H 'Content-Type: application/json' \
     -H 'Content-Length: 0' \
     -H 'ocp-apim-subscription-key: <<CONTENT_OF_THE_SUBSCRIPTION_KEY>>'

Token-Ablauf behandeln:

Tokens haben eine Ablaufzeit (expires_in), daher müssen Sie die Token-Erneuerung oder eine erneute Authentifizierung bei Bedarf verwalten.

Fehlerbehebung bei OAuth2-Problemen

Überprüfen Sie den Endpunkt-URL

Stellen Sie sicher, dass Sie die korrekte URL für den Token-Endpunkt verwenden. Überprüfen Sie die API-Dokumentation für den genauen Endpunkt und achten Sie darauf, dass keine Tippfehler vorliegen.

Prüfen Sie die Anfrage-Header

Stellen Sie sicher, dass der _Content-Type-_Header korrekt auf application/x-www-form-urlencoded gesetzt ist.

Zugangsdaten validieren

Überprüfen Sie, ob die verwendete client_id und client_secret korrekt und aktiv sind.

Diese Werte sind groß-/klein-schreibungssensitiv und müssen exakt mit den Angaben beim Onboarding übereinstimmen. Andernfalls lehnt der Autorisierungsserver die Anfrage ab.

Überprüfen Sie die Fehlermeldung, die vom Server zurückgegeben wird

Häufige Probleme umfassen:

Ungültiger Grant-Typ: Stellen Sie sicher, dass grant_type auf client_credentials gesetzt ist.

Ungültige Client-ID/Secret: Überprüfen Sie die Richtigkeit Ihrer Zugangsdaten.

Fehlende oder ungültige Parameter: Stellen Sie sicher, dass alle erforderlichen Parameter enthalten sind.

Der Autorisierungsserver könnte vorübergehend nicht in der Lage sein, die Anfrage aufgrund von Wartungsarbeiten oder anderen Problemen zu verarbeiten.

Wenn das Problem weiterhin besteht, kontaktieren Sie das API-Management-Supportteam mit detaillierten Fehlerinformationen: api-management@dkv-mobility.com