# Supervised Login source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/connect/supervised/index.md When connecting a user for the first time, a *supervised login* is performed. The user will be redirected to an authentication URL in a browser. Here, they choose their provider (bank or other financial institution) and enter their credentials. Upon successful login, an `accessToken` and a `loginToken` is issued. A *supervised login* flow consist of a series of steps that the user needs to perform. A typical example is to enter a username and password as a first step, and a one-time password as a second step. Some providers support multiple login methods. In this way, these providers allow the user to choose between using an authentication app or merely logging in with a username and a password. Therefore, there will be different supervised login flows. #### Start a supervised login {#start-a-supervised-login} Before you can start a *supervised login* , you have to initiate it by calling `/v1/authentication/initialize` which will respond with an `authUrl`. ```shell curl -X POST \ https://api.nordicapigateway.com/v1/authentication/initialize \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "userHash": "test-user-id", "redirectUrl": "https://devportal.openbanking.mastercard.com/demo/redirect" }' ``` | **Name** | **Required** | **Type** | **Description** | |--------------------|--------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `userHash` | Yes | `string` | A unique ID for the end-user. Go to [Authentication - Identifying users](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/connect/identifying-users/index.md) for more information | | `redirectUrl` | Yes | `string` | A string that contains an URL where the end-user will be redirected to after finishing the supervised login flow | | `language` | No | `string` | A string that contains the language code that the login app will use. Supports English (`en`), Danish (`da`), Norwegian (`no`), Finnish (`fi`), Swedish (`sv`), Dutch (`nl`), Estonian (`et`), Lithuanian (`lt`), German (`de`), French (`fr`), Polish (`pl`), and Spanish (`es`). If an unsupported language code is provided, the fallback language is `en` | | `providerId` | No | `string` | A string that specifies which ASPSP the end-user will log in to. Provider IDs can be obtained by calling `/v1/providers` Please note: On a regular basis, we may remove certain `providerId` values, and introduce new ones. This can happen for example when banks merge or close. We therefore recommend that your solution retrieves and validates these values from the `/v1/providers` endpoint. These values should not be hard-coded in your solution. If this field is not populated, then our flow will guide the PSU to choose their ASPSP in our "bank selector" interface. | | `providers` | No | `[string]` | An array of country codes and/or Provider IDs (obtained from `/v1/providers`). Used to filter what providers are included in the provider list. `DK`, `SE`, `FI`, `NO` | | `excludeProviders` | No | `[string]` | An array of country codes and/or Provider IDs (obtained from `/v1/providers`). Used to filter what providers are excluded in the provider list. `DK`, `SE`, `FI`, `NO` and `NL` | | `loginToken` | No | `string` | The end-user's existing login token. Include this if the user has logged on before. From this, we can extract the `providerId` and other information instead of prompting the user for it. | Note: If you include a specific provider but exclude the country with `excludeProviders`, the provider will not be shown. There is no need to set `providers` if you want to show providers for a single country. it is enough to set `providers` with the language code. This is an example response: ```json { "authUrl": "https://api.nordicapigateway.com/v1/authentication/start?startToken=ugAAAAVDaXBoZXJ0ZXh0AIAAAAAAqG8X41PoyO1Um4GsHQlqmy7c02mhontKuu2VrUBIqYzJU%2BfJ%2FuZWKmYvrBhXnpVnSDLWJsBsam9dvRCFax1Rm5KE%2FTPBTWA4oa3PtNaUWknlgGzzdFRdRss0kCE1aSCelG7lrZnN%2FXenBXRSMtTWmFfj%2FFQ2TpGgYdwznZ2uPLIFSXYAEAAAAAC1XEnqjqmz2l%2Bo0axEk7WgEEtleUlkAAAAAAAA" } ``` Navigating to `authUrl` will start the following end-user provider login flow, regardless if it is using a webview or redirecting the end-user to it. Note that iframes are not supported with most banks and we therefore do not recommend them: ![Login flow](https://static.developer.mastercard.com/content/open-finance-europe/uploads/login-flow.png) By polling the `/v1/authentication/{sessionId}/status` endpoint you can check the authentication status of the session. This endpoint returns the current state of the session. Once the authentication returns the state `Succeeded` , the response of the `/v1/authentication/{sessionId}/status` response contains the `code` needed for obtaining the [`accessToken` and `loginToken`](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/api-basics/code-and-tokens/index.md). After completing the login flow, the Payment Service User (PSU) will be redirected to the URL which was specified in `redirectUrl` when you initialized a login (by calling `/v1/authentication/initialize`). The service appends a query string to the provided `redirectUrl` with information about the result of the completed login flow. If the login was successful, the `code` is also returned as a query parameter in the `redirectUrl`. Redirect URL Example: https://aiia.eu/demo/redirect?code=qgAAAAVDaXBoZXJ0ZXh0AHAAAAAAhc3pqKXxpxfZnLBlBK8FZApw9cEVp7Fp9d0tcRGsx7Q9/t0gmKcPuh0jsny/VjT4Y7WTXZLPvmFjuCYUyKWgFeZs3iFVygNXZrtwHIocNFbRYSVHcIalV3Oleyc9JV4XcD4o/p++gDBWKRsSzipqQwVJdgAQAAAAABSXV44SuwfpjExvUiTg6IsQS2V5SWQAAAAAAAA= To use the `code` to obtain a `accessToken` and `loginToken` to then access AIS data, please refer to [Codes and Tokens](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/api-basics/code-and-tokens/index.md). #### Redirect errors and PSU drop-out {#redirect-errors-and-psu-drop-out} Error situations can occur if the PSU abandons or does not complete the login flow. In some situations our service is able to catch the error and provide information back to the Third Party Provider (TPP) in the `redirectUrl` query parameters. For example, if the PSU cancels the flow or the login times out, the PSU is redirected to `{redirectUrl}?success=false&error=`. However if the PSU closes the browser window, or is further redirected to a third-party PSD2 interface which does not handle errors gracefully, we lose the ability to determine what has happened to the PSU. No information can be provided about what went wrong for a "lost" PSU. #### Are you having problems? {#are-you-having-problems} Here are some things that can go wrong when trying to start a login flow. * `AuthenticationAlreadyStarted` -- The `authUrl` has already been used. * `SessionNotFound` -- The `authUrl` contains an unknown `startToken`. * `SessionExpired` -- The `startToken` contained in `authUrl` has expired (the `startToken` is only valid for one hour).