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

tech-partner mortgage loans consumer loans

authentication authentication




  • onboard user of any organization to integrate Europace in a tool
  • login user after user-approval


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

How to get users access_token with Europace auth-code-flow

The diagram is showing the flow and steps of the authorization process.

%%{init: {'theme': 'neutral', 'themeVariables': { 'actorBkg': '#83EEED'}}}%%
  participant usr as User
  participant br as  Browser
  participant app as User Application
  participant auth as Authorization API 
  participant ep as Europace API
  Note over usr, ep: user interaction
  activate usr
  usr ->> app: show ressource of Europace
  activate br
  activate app
  app ->> br: redirect ep-auth<br/> with state
  deactivate app
  br ->> auth: authorize response-type=code<br/> (example 1)
  activate auth
  auth ->> auth: user authenticated?
  auth ->> br: show login-page (no)
  usr ->> br: input username & pw  
  br ->> auth: username & pw
  auth ->> auth: client-approval exists?
  auth ->> br: show user-consent-page (no)
  usr ->> br: approve client & scope
  br ->> auth: approve client & scope
  auth ->> auth: create client-approval
  auth ->> br: redirect to redirect_uri<br/> with code & state
  Note over usr, ep: backend interaction
  br ->> app: code & state
  activate app
  app ->> app: check state
  app ->> auth: auth with code<br/> (example 2)
  auth ->> app: access_token &<br/> id_token
  deactivate auth
  app ->> app: decode id_token to identify user<br/> and store `sub` at user-data<br/> for later use (optional)
  app ->> ep: call EP-API with access_token
  ep ->> app: ressource-data
  app ->> br: show ressource-data
  usr ->> br: 😍
  deactivate app
  deactivate br
  deactivate usr

User interaction part

After client-registration, you can create a link for the browser to get an id-token after user-authentication and user-consent for your client (step (3) in the diagram):

This request is for all users the same and doesn’t contain sensible information.

example request 1:
&scope=[registered and needed scopes]%20openid

This link will start the authentication process in the browser. The user will be authenticated (step 4) and give the user-consent (step 8) for the requested scopes and the client.

Backend interaction part

To close the registration-circle, we call back the redirect-uri in the browser with path-param code and state (step 13). If user already authenticated and user-consent already exists, the browser will directly redirect to your redirect-uri.

Europace will redirect to: [redirect-uri]?code=[oneTimeCode]&state=[yourDataForRedirectUri]

example request 2:

State can be used to pass information through the process like sessions, user-id or security-handles.

With the code you can get an id-token for the authenticated user (step (2) in the diagram). Use your client-id and client-secret as basic authentication credentials for POST-Form with grant-type, code and redirect-uri. Usually, the redirect-uri has to be encoded.


POST /auth/token HTTP/1.1
Authorization: Basic VlVIN...
Content-Type: application/x-www-form-urlencoded



   "access_token": "eyJraWQiO...",
   "scope": "openid profile baufinanzierung:vorgang:schreiben profile baufinanzierung:vorgang:lesen",
   "id_token": "eyJraWQiOiJPTE...",
   "token_type": "Bearer",
   "expires_in": 3600

The access_token can now used with al Europace APIs.

In the process, problems could occur. In most problem-cases, we will provide the code but you can not get an access-token. You will get an error-message, which you can handle. The process ends unsuccessfully.

Possible problems:

  1. use declined the user-consent
  2. user are not allowed to use the client

How to identify the user (optional)

To get the partnerId if the user, inspect the id-token with decoding RSA256, and extract the sub-property. The id_token contains user-information in the payload if scope=profile is used. You will find a lot of libs for your prefered code-language at to decode jwt-tokens with RSA256.


  • valid id_token

Example decoded id-token with scope=openid:

  "sub": "ABC12",
  "aud": "XMLM6XIG5JALVM3V",
  "auth_time": 1620743169,
  "iss": "",
  "exp": 1620752934,
  "iat": 1620745734,
  "jti": "cS_ZHi80_W958vNV"

Example decoded id-token with scope=profile openid:

  "sub": "ABC12",
  "iss": "",
  "preferred_username": "",
  "given_name": "Theo",
  "picture": "
  "aud": "VUH5WE2SVDPBDJFD",
  "auth_time": 1620741571,
  "exp": 1620748826,
  "iat": 1620741626,
  "family_name": "Test",
  "email": "",
  "jti": "uW12IT_krnR0Zyrp"

sub contains the authenticated partnerId. You can store the partnerId on your user-data to get an access-token in the future without any user-interaction.

How to get an access-token without user-interaction (optional)

If you need access-token for backend-jobs, where the user is not present, you can get one with the partnerId of the user.

This step is not shown in the diagram.


To get the access-token use your client-id and client-secret as basic authentication credentials for POST-Form with grant-type, scope, actor and subject

example request:

POST /auth/token HTTP/1.1
Authorization: Basic VlVIN...
Content-Type: application/x-www-form-urlencoded

&scope=[registered and needed scopes]
&actor=[user partnerId]
&subject=[user partnerId]

example response:

If your client is valid and the user-consent exists and all requested scopes are registered on the client and approved by the user you should receive an access-token.

   "access_token": "eyJraWQiOi..",
   "scope": "baufinanzierung:vorgang:schreiben baufinanzierung:vorgang:lesen openid profile",
   "token_type": "Bearer",
   "expires_in": 3600