Authorization API

The Authorization API provides authentication to Europace for APIs. It is a mandatory requirement for using Europace APIs.

Documentation

related articles

• Migrationsguide.
• HowTo implement auth-code-flow

Usecases

• login user to use europace-apis with his identity

Quickstart

To test our APIs and your use case as quickly as possible, we've put together a Postman Collection for you.

How to use OAuth2?

All Europace APIs are access restricted, i.e. in order to use them a login (authentication) to Europace has to be done first.

Follow these steps:

• you have to register your client once in Europace, whereupon you will receive the Client_ID and the Client-Secret for the client.
• To log in to Europace, call https://api.europace.de/auth/token with the Client_ID and the Client_Secret as Basic-Auth to get an access_token. Most HTTP clients already support OAuth2 and can be configured with these parameters.
• With the access_token as a bearer token you can make requests to the Europace APIs. Request header variable: Authorization: Bearer [access_token]

How to register your client?

apply client-registration

Please contact [email protected] with the following data:

• EP2 PartnerId
• Client name
• Client Description:
• Contact email address for operational queries
• Short description of the use case (goal)
• required scopes

After a short check with the owner (Europace partner) we will register your client immediately and provide you with the client ID and client secret in your personal link list in Europace.

Please note that by using the APIs, you automatically agree to the Europace API Terms of Use.

How to get an access-token?

To log in to Europace, call https://api.europace.de/auth/token with the Client_ID and the Client_Secret as Basic-Auth to get an Access_Token.

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 this case, an access token is created in the name and on behalf of the partner to which the client is registered. Further use cases are discussed in "Old world - new world".

In addition to the grant type, the following request parameters are supported:

• Grant-Type (grant_type)

  OAuth2.0 Grant-Type, must be client_credentials for client credentials flow.

• Scopes (scope).

  " "-separated list of scopes. If a subject is specified, impersonate must be included as a scope. Requested scopes are restricted according to the actor's permissions and the client's approval by the actor. It is possible to request restricted access by specifying specific scopes. A scope represents an authorization to perform actions on the platform. If no scopes are requested, the scope results from the scopes stored during client registration. The currently available scopes are maintained in an Overview.

• Actor (actor)

  Partner id of the partner on whose behalf the client is acting, there must be a client-approval of the actor for the client. Currently the client-approval is granted automatically during registration for the actor and all subjects in the access area of the client.

• Subject (subject)

  Partner id of the partner on whose behalf the client acts. The subject must be subordinate to the actor.

How to call an API with access-token?

With the Access_Token as a Bearer token you can make requests to the Europace APIs. Request header variable: Authorization: Bearer [access_token]

Using the example of the process API in curl:

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

How to authenticate different users with one client? (Impersonation)

The imperseded OAuth2 method is used when the API needs the specific user and you don't want to register a client for each user. It is enough to have one client for the organization that acts as a general key and can be used to log in users that the organization has access to.

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=[to be login PartnerID]' \
--data-urlencode 'actor=[registered PartnerID]'

Parameters	Description
Subject	the PartnerID of the user to be registered
Actor	the partnerID of the registered client Note: The Actor partnerid must be placed above the Subject partnerid in the partner management structure, otherwise the necessary access rights are missing. There can be any number of scopes between the partnerids.
Scope	required scopes of the token Note: The scope impersonate must always be included. All specified scopes must be enabled at the client.

Terms of use

The APIs are made available under the following Terms of Use.

Support

If you have any questions or problems, you can contact [email protected].