# Connect Flow
source: https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/connect/connect-flow/index.md

Connect Flow is where end users provide consent and connect their bank account(s). The flow can be found at [app-sandbox.aiia.eu](https://app-sandbox.aiia.eu) and this is also where you will be asked to redirect end users to when calling our `/v1/oauth/connect/` endpoint. When calling this endpoint, you define the functionality that you want the end user to use through your service as [Scope](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/connect/scopes/index.md).

To start the Connect flow and request the end user to allow access to account data, call the Initialize endpoint as shown below:

API Reference: `GET /v1/oauth/connect`

```shell
curl -D- -G \
  https://api-sandbox.aiia.eu/v1/oauth/connect \
  -d client_id=<CLIENT_ID> \
  -d redirect_uri=<REDIRECT_URL> \
  -d scope="accounts offline_access" \
  -d response_type=code \
  -d accountsGroupName=<optional> \
  -d accountsGroupId=<optional>
```

The `redirect_uri` is where the user is redirected to after finishing the login flow. This needs to match one of the redirects you specified when you created your application on the [Developer Portal](https://devportal.openbanking.mastercard.com/).
Tip: For mobile apps, you should supply an [iOS Universal Link](https://developer.apple.com/ios/universal-links/) or [Android App Link](https://developer.android.com/training/app-links#android-app-links) for `redirect_uri`.

We do not recommend using a deep link (custom URL scheme) for `redirect_uri` since deep links lack the security of iOS Universal Links and Android App Links.

Any application can register custom URL schemes and there is no further validation from iOS or Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. A deep link can also trigger an alert on iOS devices that can add friction to the customer experience.
Note: The `scope` parameter is optional. If not specified, the default value of `accounts offline_access` is used. This default matches the access rights that were used prior to introducing the scope parameter, retaining backwards compatibility. Note: It will result in an additional cost to use Group functionality. Contact [Sales](https://openbankingeu.mastercard.com/contact-us) for further information and pricing.

Connect flow is very similar to the OAuth flow that you might be familiar with. We need to get consent from your users to fetch data and pass that data on to you.

The response will be a `302 Found` that you need to follow. Look in the location header to figure out where you should redirect to.

```HTTP
Location=https://api.aiia.eu/v1/oauth/connect?client_id=%3Cstring%3E&redirect_uri=%3Cstring%3E&response_type=%3Cstring%3E
```

After you have redirected the end users to the URL, they will go through the following steps.

#### Step 1 {#step-1}

In the first step, new end users are asked to give their consent before we can retrieve bank data on their behalf.

![Step 1](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-1a.png)

#### Step 2 {#step-2}

In the next step, end users are directed to the connection flow.

Here, they will select what bank provider they want to use.

![Step 2](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-2ia.png)

#### Step 3 {#step-3}

Now, end users need to log in to their bank account using one of the available login methods.

![Step 3](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-3a.png)

#### Step 4 {#step-4}

In this step, end users will come back to the Connect Flow.
Here, they will be presented with a list of possible bank accounts that will be shared with your service through our APIs.

![Step 4](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-4a.png)

#### Step 5 {#step-5}

In this step, end users enter their email. The email will be associated with their Hub account.

![Step 5](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-5a.png)

#### Step 6 {#step-6}

Shortly after, end users will receive an email with a verification code. End users need to enter this code when they do a [Supervised](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/connect/supervised/index.md) login in the future.

![Step 1](https://static.developer.mastercard.com/content/open-finance-europe/uploads/flow-step-6a.png)

#### Access token retrieval {#access-token-retrieval}

Once end users have completed the connection flow, they will be redirected back to your specified `redirect_uri`. This redirect will have a query parameter called `code` sent with it, which you need to gain an access token.
Note: `code` is not URL safe, meaning that it will be [URL encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) . `code` will need to be URL-decoded before the next step. Some web frameworks might do that automatically.

With that code, you can call the endpoint like this:

```shell
curl -X POST \
  https://api-sandbox.aiia.eu/v1/oauth/token \
  -u <CLIENT_ID>:<CLIENT_SECRET>
  -H 'Content-Type: application/json' \
  -d '{
        "grant_type" : "authorization_code"
        "code": "<CODE>"
        "redirect_uri" : "<REDIRECT_URL>"
      }'
```

Along with the `code`, you get a `consentId`. This id is your representation of a user and is valid as long the user has given his or her consent for you to fetch data. A good idea is to store this id along with your tokens. We use this id when we send you webhooks.

##### Authorization header in `/oauth/token` {#authorization-header-in-oauthtoken}

The `Authorization` header in `/oauth/token` endpoints uses `Basic` HTTP Authentication scheme (which is defined in [rfc7617](https://tools.ietf.org/html/rfc7617)).
In other words, the value of the header is `Basic {"<CLIENT_ID>:<CLIENT_SECRET>" string encoded as base64}`.

Here are code examples of how to do in C#, Java, JavaScript and Python:
* Csharp
* Java
* Javascript
* Python

```csharp
string GenerateBasicAuthorizationHeaderValue(string clientId, string clientSecret)
{
  var credentials = $"{clientId}:{clientSecret}";
  var credentialsByteData = Encoding.GetEncoding("iso-8859-1").GetBytes(credentials);
  var base64Credentials = Convert.ToBase64String(credentialsByteData);
  return $"Basic {base64Credentials}";
}
```

```java
import java.util.Base64;

public String generateBasicAuthorizationHeaderValue(String clientId, String clientSecret)
{
    String valueToEncode = clientId + ":" + clientSecret;
    return "Basic " + Base64.getEncoder().encodeToString(valueToEncode.getBytes());
}
```

```javascript
function generateBasicAuthorizationHeaderValue(clientId, clientSecret) {
    const toEncode = clientId + ":" + clientSecret;
    const encoded = btoa(toEncode);
    return "Basic " + encoded;
}
```

```python
from base64 import b64encode

def generate_basic_authorization_header_value(clientId, clientSecret):
    token = b64encode(f"{clientId}:{clientSecret}".encode('utf-8')).decode("ascii")
    return f'Basic {token}'
```

<br />

Note: A `code` can only be used once and expires after one minute.

The response contains two tokens, `access_token` and `refresh_token`. An example of a successful response:

```json
{
  "access_token": "eyJhbGciOiJIUzI1Ni978juanR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJmYTE4OTI3MS1mOTY1LTRmNWMtOTlmOS1lNDViNzNiYzI4MzkiLCJjbGllbnRJZCI6InZpaWEtZnBwIiwicm9sZSI6IkNsaWVudFVzZXIiLCJzZ67623aW9uSWQiOiJlZmE1NWU0ZS0xZTUxLTQ1YWMtYWEyYy01OThhNjFjMTZlOTYiLCJuYmYiOjE1Njc0MTQxNzMsImV4cCI6MTU2NzQxNzc3MywiaWF0IjoxNTY3NDE0MTczfQ.7QD6zGcdonYy79384buXOqsykWrbWa3L6LW4d9uzb-zA",
  "expires_in": 3600,
  "redirect_uri": "https://httpbin.org/anything",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI687234pXVCJ9.eyJ1c2VySWQiOiJmYTE4OTI3MS1mOTY1LTRmNWMtOTlmOS1lNDViNzNiYzI4MzkiLCJjbGllbnRJZCI6InZpaWEtZnBwIiwiY29uc2VudElkIjoiYTYyODExYWYtNzUxMS00ZWQ0LoyiauasiYTEtMjAwNzc2NGQ1MTIwIiwic2Vzc2lvbklkIjoiZWZhNTVlNGUtMWU1MS00NWFjLWFhMmMtNTk4YTYxYzE2ZTk2Iiwicm9sZSI6IlJlZnJlc2hUb2tlbiIsIm5iZiI6MTU2NzQxNDE3MywiZXhwIjoxNTY4NjIzNzczLCJpYXQiOjE1Njc0MTQxNzN9.5-x0NNg5lMxPnZRYtu983764q0sbPcSb7U9b23e3Zwx0Ss9I",
  "token_type": "bearer"
}
```

## Keeping state {#keeping-state}

Keeping state in a multi-tenant application is essential. This is easily done with Connect Flow, as we allow you to choose how you want to do it.

#### Wildcard {#wildcard}

We support wildcards in all of your redirect URLs.

A wildcard is a catch-all functionality. Place an `*` in your registered redirect URL ex. `https://mydomain.com/aiia-callback/*`
Note: We do not support wildcard in domain and sub-domain.

#### OAuth State {#oauth-state}

The primary reason for using the state parameter is to mitigate CSRF (Cross-site Request Forgery) attacks. You can also use the state parameter to encode an application state that will round-trip to the client application after the Connect Flow is complete. In this way, the application can redirect the user to where they were before the authentication process happened.

```shell
curl -G \
  https://api-sandbox.aiia.eu/v1/oauth/connect \
  -d client_id=<CLIENT_ID> \
  -d redirect_uri=<REDIRECT_URL> \
  -d response_type=code  \
  -d state={your_state}
```