Dokumentation

Sofort startklar mit dem API Hub

Unsere API Dokumentation soll Sie bei Ihrer Entwicklung unterstützen.

Registrierung Ihres Entwickler-Accounts

Eine Registrierung im API Hub ermöglicht Ihnen, den kompletten Katalog der verfügbaren Commerzbank APIs erleben zu können. Die Anmeldung ist für Sie jederzeit kostenlos. Klicken Sie hierzu einfach auf „Registrieren“.

Tragen Sie Ihren Vor- und Nachnamen, Emailadresse und Telefonnummer (optional) ein und legen Sie Ihr persönliches Passwort fest. Das Passwort muss hierbei mindestens 8 Zeichen lang sein.

Im Anschluss erhalten Sie einen Aktivierungslink per Email von uns zugeschickt. Nach Aktivierung Ihres Accounts können Sie sich in unseren API Hub einloggen, den API Katalog einsehen und Ihre App registrieren.

Die Angaben zu Ihrem Account können Sie jederzeit nach dem Login unter „My Account“ einsehen und anpassen.



API Katalog

Im API Katalog der Commerzbank finden Sie alle für Sie verfügbaren APIs. Eine Such- und Filterfunktion erleichtert Ihnen hierbei die Nutzung des API Katalogs.

Wesentliche Features, wie die API Kategorie (z.B. Kredit oder Personendaten), sehen Sie bereits in der Übersicht und können ebenso nach dieser filtern. Weitergehende Informationen sowie alle nötigen technischen Details für die Integration in Ihre Anwendung erhalten Sie unter den Detailinformationen einer jeden API.

Sie wurden in unserem Katalog nicht fündig? Kontaktieren Sie uns und teilen uns Ihren individuellen Wunsch mit.



Registrieren Sie Ihre App

  1. Registrieren Sie sich im Commerzbank API Hub mit Ihren persönlichen Anmeldeinformationen (Name, Emailadresse) und legen Sie ein Passwort fest.
  2. Falls Sie bereits registriert sind, können Sie sich direkt über den Login mit Ihrer Emailadresse und Passwort anmelden.
  3. Klicken Sie in der Navigationsleiste auf „Apps“.
  4. Für die Registrierung Ihrer App zur Sandboxnutzung klicken Sie auf den Button „Create application“
  5. Geben Sie Ihrer App einen Namen. Optional können Sie eine Emailadresse, Kurzbeschreibung Ihrer App und Telefonnummer hinzufügen.
  6. Um die App erfolgreich anzulegen, achten Sie bitte darauf, dass der Haken bei „Enable Authentication“ gesetzt ist.
  7. Wählen Sie zu Ihrer App die individuell gewünschten APIs aus. Um die Zuordnung zu Ihrer App zu erleichtern, können Sie nach Ihrer favorisierten API suchen. Die ausgewählten APIs sind mit einem Haken in der Spalte „Selected“ markiert.
  8. Klicken Sie „Save application“. Nun ist Ihre App registriert. Ein zusätzliches Absenden der Eingaben ist nicht mehr nötig.
  9. Sie gelangen auf die App-Übersicht, wo Sie Ihre registrierte App nun finden.
  10. Klicken Sie auf Ihre App, um auf die Detailseite zu gelangen.
  11. Hier können Sie unter „API Key“ oder „OAuth Credentials“ Ihre Credentials für eine spätere Authentifizierung an der Sandbox erstellen. Klicken Sie für die Erstellung eines Credentials auf „Edit the application“, wählen die gewünschte Methode aus (API Key oder OAuth) und erstellen Sie mit dem Button „Generate“ ein neues Credential.
  12. Das neue Credential wird nun angezeigt. Zum Aufzeigen des jeweiligen Secret Keys, klicken Sie bitte auf den „Actions“- Button und wählen „View secret“ aus.
  13. Ihre App ist jetzt zum Entwickeln bereit.
  14. Zur Unterstützung Ihrer Entwicklung können Sie unsere Sandbox mit Mock-Daten zum Testen Ihrer App nutzen. Für die Nutzung der Sandbox müssen Sie den erstellten API Key bzw. das OAuth Credential sowie den jeweiligen Secret Key in Ihre App integrieren.

Ihre registrierten Apps können Sie jederzeit in der Navigationsleiste unter „Apps“ nach Login verwalten auf der Detailseite einsehen und über den Button „Edit application“ ändern oder mit dem Button „Delete application“ jederzeit wieder löschen.



Testen Ihrer App

Um Ihre Entwicklung zu unterstützen, können Sie die zugeordneten APIs in der Sandbox testen. Ein Aufruf der API, mit der generierten und gültigen Authentifizierungsmethode, gibt Ihnen Testwerte (Mock-Daten) zurück.



Nutzung der API mit Echtdaten

Für die Nutzung der Live APIs (Echtdaten) benötigen Sie aus Sicherheitsgründen ein Commerzbank Transportzertifikat (von der Commerzbank signiertes Client-Zertifikat). Der Support hilft Ihnen gerne weiter.

Im weiteren Verlauf können Sie die Nutzungsstatistiken Ihrer App jederzeit bequem in Ihrem Account einsehen.



Security

API-Autorisierung Einführung

Bevor Sie in Ihrer Client-Anwendung auf Commerzbank-APIs zugreifen können, muss die Client-Anwendung für den Zugriff autorisiert sein. Falls die aufgerufenen APIs personenbezogene Kundendaten liefern, muss dieser Zugriff von dem Kunden genehmigt werden. In diesem Fall müssen Sie das OAuth 2.0-Protokoll zur Autorisierung verwenden. Wenn keine personenbezogenen Daten von einer API geliefert werden, kann die API mit einem API-Key aufgerufen werden.

Die Informationen, ob Sie mit einem OAuth 2.0- oder API-Key auf eine API zugreifen können, sind für jede API im API-Katalog dokumentiert.

OAuth 2.0

OAuth 2.0 ist ein Industriestandardprotokoll für die API-Autorisierung. OAuth 2.0 definiert vier logische Rollen:




OAuth Role Beschreibung
Resource Owner Eine Person (z. B. Commerzbank-Kunde), die einer Anwendung Zugriff auf personenbezogene Daten (z. B. Kontoinformationen) gewährt. Resource Owner ist der Benutzer Ihrer Anwendung.
Client Der Client ist die Anwendung, die Sie entwickeln und die versucht, auf die Commerzbank-Daten zuzugreifen. Damit die Client Anwendung auf die Daten zugreifen kann, benötigt sie eine Erlaubnis vom Resource Owner.
Resource Server Der Ressource Server ist der Server, der APIs hostet, die Sie in Ihre Anwendung integrieren, um auf die Daten des Resource Owner zuzugreifen. Der Ressource Server wird von der Commerzbank bereitgestellt und kontrolliert.
Authorization Server Der Authorization Server stellt die Schnittstellen für den Bezug von Access Token bereit und erstellt Access Token für Client Anwendungen, damit Zugriffe auf APIs erfolgen können. Der Authorization Server wird von der Commerzbank bereitgestellt und kontrolliert.

API-Key

Wenn keine personenbezogenen Daten von einer API geliefert werden, kann mit einem API-Key auf die APIs zugegriffen werden.




Credential Registrierung

Das folgende Bild zeigt, wie API-Keys und OAuth 2.0 Credentials im Entwicklerportal für Client Anwendungen erzeugt werden:




API-Key Attribute

Attribut Beschreibung
API Key API-Key ID
Javascript Origin (Javascript Ursprünge) Nicht relevant
Erstellt am Erstellungsdatum
Aktionen / Secret Zeigt das Secret für den API-Key an.


OAuth-Anmeldeinformationen

Attribut Beschreibung
Client ID Client Identifier
Type Confidential oder public Client
Javascript Origin (Javascript Ursprünge) Nicht relevant
Redirect URLs Eine kommaseparierte Liste mit erlaubten Redirect URLs
Created Erstellungsdatum
Actions/View Secret Zeigt das OAuth-Secret für die Client-ID an.


OAuth 2.0 Grant-Types

OAuth 2.0 unterstützt verschiedene Methoden zum Abrufen eines Access Tokens von einem Authorization Server. In OAuth werden diese verschiedenen Arten als Grant-Types bezeichnet. Die folgenden 3 Grant-Types werden von Commerzbank APIs unterstützt.

Authorization Code Grant Type

Dies ist der Standard-Grant-Type, wenn Sie auf APIs der Commerzbank zugreifen möchten. Der Grant Type erfordert, dass ein Client in der Lage sein sollte, ein Client-Secret geheim zu halten. In OAuth wird ein solcher Client als confidential bezeichnet. Dieser Grant-Typ beinhaltet eine Interaktion mit dem Resource Owner.

Client Credentials Grant Type

Der Client Credentials Grant-Type beinhaltet keine Authentifizierung und Interaktion des Resource Owner. Daher sendet der Client nur die Client-ID und das entsprechende Secret an den Autorisierungsserver, um ein Access Token zu erhalten.

Refresh Token Grant Type

Der Refresh-Grant-Type wird verwendet, um ein Refresh Token gegen ein Access Token zu tauschen.

OAuth Autorisierung im Detail

Authorization Code Grant



1. Der Endnutzer initiiert einen API Aufruf.

2. Die Client-Anwendung stellt eine Autorisierungsanfrage an die Commerzbank.

                
HTTP/1.1 302 Moved Temporarily

Location: https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/auth?client_id={{Client_ID}}

&response_type=code&redirect_uri={{RedirectUri}}

                
            
Parameter Description
Client_ID Client Identifier
Redirect URLs Eine kommaseparierte Liste mit erlaubten Redirect URLs

3. Der Nutzer meldet sich mit seinen Credentials an (Login).

4. Der Nutzer erteilt der Client Anwendung die angefragten Berechtigungen (Consent).

5. Die Anwendung erhält den Authorization Code in der Response von der Commerzbank.

                
HTTP 302 Found??

Location: https://{{RedirectUri}}?code={{AuthorizationCode}}
                
            

6. Der Authorization Code wird gegen ein Access Token getauscht. Die Client Credentials sind mit Base64 Verfahren encoded im Autorisierungsheader enthalten.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={{Client_ID}}&client_secret={{Secret}}&code=

{{AuthorizationCode}}
&redirect_uri={{RedirectURI}}
                
            

6.1 Auf der Sandbox lautet die Tokenmanager URL wie folgt:

                
https://api-sandbox.commerzbank.com/auth/realms/sandbox/protocol/openid-connect/token
                
            

7. In der Antwort der Commerzbank wird ein Access Token geliefert.

                
HTTP 200 OK

Content-type: application/json?
{?
    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?
}
                
            

8. Zugriffe auf APIs der Commerzbank erfolgen mit dem Access Token, das Base64 encoded im Authorization Header übertragen wird.

                
GET https://api.commerzbank.com/api_operation 

Authorization: Bearer 1723ghhjkiu6trfref57thgjhg
                
            

Client Credentials Grant Type



1. Der Endnutzer initiiert einen API Aufruf.

2. Die Client-Anwendung stellt eine Autorisierungsanfrage an die Commerzbank.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{Client_ID}}&client_secret={{Secret}}
                
            

3. In der Antwort der Commerzbank wird ein AccessToken ausgeliefert.

                
HTTP 200 OK

Content-type: application/json?
{?

    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?
    "refresh_token":" fdb8 ... 209c "?
}
                
            

4. Zugriffe auf Commerzbank-APIs erfolgen mit dem Access Token, das Base64 encoded im Authorization Header übertragen wird.

                
GET https://api.commerzbank.com/api_operation 

Authorization: Bearer 1723ghhjkiu6trfref57thgjhg
                
            

Refresh Token Grant Type



1. Ein Refresh Token wird gegen ein Access Token getauscht.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

refresh_token=fdb8 ... 209c&grant_type=refresh_token
                
            

2. In der Antwort der Commerzbank wird ein AccessToken geliefert.

                
HTTP 200 OK

Content-type: application/json?
{?
    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?,
    "refresh_token":" dfb8 ... 5784x "?
}
                
            

3. Zugriffe auf Commerzbank-APIs erfolgen mit dem Access Token, das Base64 encoded im Authorization Header übertragen wird.

Sandbox Security

Um Ihre Entwicklung zu unterstützen, können Sie die zugeordneten APIs in der Sandbox testen. Ein Aufruf der API, mit der generierten und gültigen Authentifizierungsmethode, gibt Ihnen Testwerte (Mock-Daten) zurück.

Die Security Mechanismen der Sandbox entsprechen den Security Mechanismen der produktiven Umgebung. In der Sandbox wird aber keine Consent-Seite für den Authorization Code Grant Flow angezeigt. Die Consent-Erteilung erfolgt implizit. Dadurch kann in der Sandbox bereits die produktive Security getestet werden. Hierfür stehen Ihnen eigens Test-Credentials bereit:

Kennung: 1234567890

Passwort: 12345

Mit diesen Credentials kann ein Nutzer-Login durchgeführt werden.