Europace AG
Heidestraße 8, D-10557 Berlin
devsupport@europace2.de

Authorization API

Mit dieser API lässt sich ein OAuth Access Token anfordern, mit dem andere Europace-APIs verwendet werden können.


Die Authorization-API stellt die Authentifizierung bei Europace für APIs zur Verfügung. Sie ist eine zwingende Voraussetzung zur Verwendung von Europace APIs.

Vertrieb Produktanbieter Baufinanzierung Privatkredit

Authentication YAML Github

GitHub release Pattern

Check YAML with Linter Create Scopes Doc

Migrationsguide

Als Unterstützung für den Wechsel von den bisherigen Authentifizierungsverfahre auf OAuth2 gibt es diesen Migrationsguide.

Anwendungsfälle

  • Benutzer anmelden, um Europace-APIs zu verwenden

Schnellstart

Damit du unsere APIs und deinen Anwendungsfall schnellstmöglich testen kannst, haben wir eine Postman-Collection für dich zusammengestellt.

Wie benutze ich OAuth2?

Alle Europace-APIs sind zugangsbeschränkt, d.h. um sie verwenden zu können muss zuvor eine Anmeldung (Authentifizierung) bei Europace erfolgen.

Dabei müssen folgende Schritte durchlaufen werden:

  • Einmalig musst du deinen Client in Europace registrieren lassen, woraufhin du die Client_ID und das Client-Secret für den Client erhältst
  • Für die Anmeldung an Europace rufst du https://api.europace.de/auth/token mit der Client_ID und dem Client_Secret als Basic-Auth auf, um einen Access_Token zu erhalten. Die meisten HTTP Clients unterstützen OAuth2 bereits und lassen sich mit diesen Parametern konfigurieren.
  • Mit dem Access_Token als Bearer-Token kannst du Requests an den Europace APIs durchführen. Request-Header-Variable: Authorization: Bearer [Access_Token]

Wie bekomme ich einen Client registriert?

zur Client-Registrierung

Bitte wende dich an helpdesk@europace.de mit folgenden Daten:

  • EP2-PartnerId
  • Client-Name
  • Client-Beschreibung:
  • Kontakt-Email-Adresse für betriebliche Rückfragen
  • Kurze Beschreibung des Anwendungsfalls (Ziel)
  • benötigte Scopes

Nach einer kurzen Prüfung beim Eigentümer (Europace Partner) registrieren wir dir deinen Client umgehend und stellen dir die Client-ID und das Client-Secret in deiner persönlichen Linkliste in Europace zur Verfügung.

Linksammlung.png

Bitte beachte, dass du dich mit der Benutzung der APIs automatisch mit den Europace API-Nutzungsbedingungen einverstanden erklärst.

Wie bekomme ich einen Access-Token?

Für die Anmeldung an Europace rufst du https://api.europace.de/auth/token mit der Client_ID und dem Client_Secret als Basic-Auth auf, um einen Access_Token zu erhalten.

Request:

curl --location --request POST 'https://api.europace.de/auth/token' \
--user '[Client_ID]:[Client_Secret]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Response:

{  "access_token": [Access_Token],
   "scope": [verfügbare Scopes],
   "token_type": "Bearer",
   "expires_in": 3600   }

In diesem Fall wird ein Access-Token im Namen und im Auftrag des Partners erstellt an dem der Client registriert ist. Weitere Anwendungsfälle werden in “Alte Welt - neue Welt” behandelt.

Wie rufe ich eine API mit Access-Token auf?

Mit dem Access_Token als Bearer-Token kannst du Requests an den Europace APIs durchführen. Request-Header-Variable: Authorization: Bearer [Access_Token]

Am Beispiel der Vorgaenge-API in curl:

curl --location --request GET 'https://api.europace2.de/v2/vorgaenge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Access_Token]

In diesem Fall wird ein Access-Token im Namen und im Auftrag des Partners erstellt an dem der Client registriert ist.

Neben dem Grant-Type werden folgende Request-Parameter unterstützt:

  • Grant-Type (grant_type)

    OAuth2.0 Grant-Type, muss für den Client-Credentials-Flow client_credentials sein.

  • Scopes (scope)

    "`"-separierte Liste von Scopes. Wird ein Subject angegeben mussimpersonieren` als Scope enthalten sein. Angefragte Scopes werden entsprechend der Rechte des Akteurs und dem Client-Approval durch den Akteur eingeschränkt. Es ist möglich einen eingeschränkten Zugriff anzufragen, in dem man spezifische Scopes angibt. Ein Scope stellt eine Berechtigung zum Ausführen von Aktionen auf der Plattform dar. Werden keine Scopes angefragt ergibt sich der Scope aus den bei der Client-Registrierung hinterlegten Scopes. Die aktuell verfügbaren Scopes werden in einer Übersicht gepflegt.

  • Akteur (actor)

    Partner-Id des Partners in dessen Auftrag der Client agiert, es muss ein Client-Approval des Akteurs für den Client vorliegen. Aktuell wird der Client-Approval automatisch bei der Registrierung für den Aktuer und alle Subjects im Zugriffsbereich des Clients erteilt .

  • Subject (subject)

    Partner-Id des Partners in dessen Namen der Client agiert. Das Subject muss dem Akteur untergeordnet sein.

Wie authentifiziere ich verschiedene Benutzer mit einem Client? (Impersionieren)

Das impersionierte OAuth2-Verfahren wird dann verwendet, wenn die API den konkreten Benutzer benötigt und man nicht für jeden Benutzer einen Client registrieren möchte. Es reicht einen Client für die Organisation zu haben, der als Generalsschlüssel fungiert und mit dem Benutzer, auf die die Organisation Zugriff hat, angemeldet werden können.

curl --location --request POST 'https://api.europace.de/auth/token' \
--user '[ClientID]:[ClientSecret]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=impersonieren baufinanzierung:echtgeschaeft baufinanzierung:vorgang:lesen baufinanzierung:ereignis:lesen baufinanzierung:antrag:lesen' \
--data-urlencode 'subject=[anzumeldende PartnerID]' \
--data-urlencode 'actor=[registrierte PartnerID]'

Parameter | Beschreibung --- | ---   Subject | die Partnerid des anzumeldenden Benutzers | Actor | die Partnerid des registrierten Clients | Hinweis | die Actor-Partnerid muss in der Partnermanagementstruktur über der Subject-Partnerid angeordnet sein, da sonst die notwendigen Zugriffsrechte fehlen. | Scope | muss impersonieren enthalten (Hinweis: Wenn ein Scope angegeben wird, müssen alle erforderlichen Rechte angegeben werden, d.h. impersonieren allein macht keinen Sinn.) |

Nutzungsbedingungen

Die APIs werden unter folgenden Nutzungsbedingungen zur Verfügung gestellt.

Support

Bei Fragen oder Problemen kannst du dich an devsupport@europace2.de wenden.

Wir sind für Dich da! Wir beantworten gerne alle Fragen