# One-to-Many Access Model
source: https://developer.mastercard.com/open-finance-data/documentation/features/one-to-many-access-model/index.md

### Overview {#overview}

Mastercard Open Finance supports a one-to-many access model that enables you, as an Integrator, to call APIs when providing a service to multiple third-parties through a single integration. Rather than each third-party connecting to the platform independently, you act as the single point of integration, orchestrating consent flows, retrieving End User-authorized data, and delivering services to third-parties. In this model, you hold the integration relationship with the platform, apply business logic, and are accountable for how access is exercised for each third-party.

This model supports two types of third-party, reflecting different regulatory and technical arrangements.

* A Licensed third-party holds its own regulatory licence, for example, as a third-party Provider under PSD2, and provides its own Open Banking certificates for Financial Institution connectivity.
* An Unlicensed third-party operates under your licence. No separate certificates are required, and the platform uses your credentials for provider connectivity.   

Both types are onboarded and managed through you as the Integrator. Third-parties do not call the platform directly.

The relationship that authorizes you to act on a third-party's behalf is established during onboarding. Once this relationship is in place, you can obtain access tokens scoped to that third-party and make API calls, creating consents, executing flows, and retrieving data, all attributed to the third-party. Consents and data are owned by the third-party. For reporting and billing purposes, activity can be aggregated at the Integrator level.

### How it Works {#how-it-works}

You authenticate with Mastercard Open Finance using your own credentials. When calling in the context of providing a service to a third party, include the third party's ID in the token request using the X-On-Behalf-Of header. Mastercard Open Finance validates the relationship and issues an access token scoped to the third-party, with an actor claim identifying you as the Integrator. You then use this token --- together with the third-party's Application ID in the X-Application-Id header --- to create consents, execute flows, and access data on their behalf.

1. The Integrator calls `POST /oauth2/tokens`.

         Header: X-On-Behalf-Of: <indirect_client_id> 

         Body:   client_credentials grant with private_key_jwt + DPoP 

2. Mastercard Open Finance validates the relationship and then issues an access token.

         Token payload: 

         { 

           "sub": "<indirect_client_id>", 

           "act": { "sub": "<integrator_client_id>" } 

         }

3. The Integrator initiates API calls (for example, `POST /consents`, `GET /accounts`)

         Header: Authorization: Bearer <access_token> 

         Header: X-Application-Id: <indirect_client_application_id> 

### Getting Started {#getting-started}

##### Integrator Onboarding {#integrator-onboarding}

Complete these steps once when setting up your integration:

* Provide your company legal name, primary and technical contact details, and countries of operation.
* Provide a TLS certificate from an accepted certificate authority.
* Receive your identifiers from the Delivery team: Client ID, Application ID, and Use Case Configuration IDs.

##### Third-party Onboarding {#third-party-onboarding}

Repeat these steps for each third-party you wish to serve:

* Provide the third-party's legal name, type (licensed or unlicensed), countries of operation, and required products or use cases.
* For licensed third-parties only, provide Open Banking certificates for Financial Institution connectivity, either through a custom signing service or Azure Key Vault.
* Receive the third-party's identifiers: Client ID and Application ID.

Unlicensed third-parties operate under your licence. No additional certificates are required.

##### Requesting an Access Token when Providing a Service to a Third-Party {#requesting-an-access-token-when-providing-a-service-to-a-third-party}

To obtain an access token scoped to a third-party, call the token endpoint with your credentials and the third-party's ID.

**Step 1 --- Prepare the Token Request**

Call `POST /oauth2/tokens HTTP/1.1`

    Host: auth.openbanking.mastercard.eu 

    X-On-Behalf-Of: <indirect_client_id> 

    DPoP: <dpop_jwt> 

    Content-Type: application/x-www-form-urlencoded 

    grant_type=client_credentials 

    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer 

    &client_assertion=<integrator_private_key_jwt> 

    &scope=consents:create 

|      **Field**      |                              **Description**                               |
|---------------------|----------------------------------------------------------------------------|
| `X-On-Behalf-Of`    | The third-party's ID --- identifies which third-party this request is for. |
| `client_assertion ` | A signed JWT using your private key. The sub-claim must be your Client ID. |
| `DPoP`              | A DPoP proof JWT bound to this specific request.                           |
| `scope`             | The requested scope, for example `consents:create` or `ob_data`.           |

**Step 2 --- Interpret the Response**

The access token is a JWT with this structure.

| **Claim** |       **Value**        |                    **Description**                    |
|-----------|------------------------|-------------------------------------------------------|
| `sub`     | `<indirect_client_id>` | The third-party on whose behalf the token was issued. |
| `act.sub` | `<indirect_client_id>` | You, the Integrator that requested the token.         |
| `scope`   | `Requested scope`      | The permissions granted.                              |

Note: Cache access tokens per third-party and monitor the `expires_in` value. Request a new token before the current one expires to avoid interruptions. Do not reuse tokens across third-parties.

#### Using the API in a Third-Party Context {#using-the-api-in-a-third-party-context}

Once you have an access token, include it as a Bearer token in API requests. Always include the third-party's Application ID.

#### Creating a Consent when Providing a Service to a Third-Party: {#creating-a-consent-when-providing-a-service-to-a-third-party}

Call `POST /consents HTTP/1.1`

    Host: api.openbanking.mastercard.com 

    Authorization: Bearer <access_token> 

    X-Application-Id: <indirect_client_application_id> 

    Content-Type: application/json 

     

    { "..." } 

#### Retrieving Accounts when Providing a Service to a Third-Party: {#retrieving-accounts-when-providing-a-service-to-a-third-party}

Call `GET /accounts HTTP/1.1`

    Host: api.openbanking.mastercard.com 

    Authorization: Bearer <consent_scoped_access_token> 

    X-Application-Id: <indirect_client_application_id> 

These headers are required on all API calls made in a third-party context.

|     **Header**     |             **Value**              | **Required** |
|--------------------|------------------------------------|--------------|
| `Authorization`    | `Bearer <access_token>`            | Yes          |
| `X-Application-Id` | `<indirect_client_application_id>` | Yes          |

#### Licensed and Unlicensed Third-Parties {#licensed-and-unlicensed-third-parties}

The intermediated access model accommodates both types of third-party, with differing regulatory and technical requirements.

|             **Aspect**             |           **Licensed third-party**           |     **Unlicensed third-party**      |
|------------------------------------|----------------------------------------------|-------------------------------------|
| Regulatory status                  | Holds own licence (for example, PSD2 TPP)    | Operates under your licence         |
| Certificates                       | Own Open Banking certificates required       | No additional certificates          |
| Financial Institution connectivity | Platform uses the third-party's certificates | Platform uses your certificates     |
| Onboarding                         | Certificate provisioning required            | Streamlined --- no certificate step |

### Best Practices {#best-practices}

* Credential security: Store your OAuth private keys in a secure vault (HSM recommended). Never share your credentials with third-parties.
* Token management: Cache access tokens per third-party. Tokens are third-party-specific. Do not reuse tokens across third-parties. Implement token refresh before expiration.
* Identifier tracking: Maintain a mapping of third-party business identifiers to Mastercard Client IDs. Store Application IDs alongside Client IDs for each third-party.
* Accountability and intermediation: Third-parties do not interact with the platform directly. All API calls are made by you, the Integrator, acting on each third-party's behalf. You are responsible for ensuring that access is exercised appropriately and within the scope authorized by each third-party.

### Next Steps {#next-steps}

Now that you understand the intermediated access model, explore these sections to continue your integration:

* [API Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md) for details on key generation, JWT signing, and token management.
* [API Reference](https://developer.mastercard.com/open-finance-data/documentation/api-reference/index.md) for the full endpoint specification.
* [Use Cases](https://developer.mastercard.com/open-finance-data/documentation/use-cases/index.md) for examples of what you can build with Mastercard Open Finance.   

Contact [Mastercard support](mailto:openbankingeu_support@mastercard.com) to begin Integrator and third-party registration.


# One-to-Many Access Model
source: https://developer.mastercard.com/open-finance-data/documentation/features/one-to-many-access-model/index.md

### Overview {#overview}

Mastercard Open Finance supports a one-to-many access model that enables you, as an Integrator, to call APIs when providing a service to multiple third-parties through a single integration. Rather than each third-party connecting to the platform independently, you act as the single point of integration, orchestrating consent flows, retrieving End User-authorized data, and delivering services to third-parties. In this model, you hold the integration relationship with the platform, apply business logic, and are accountable for how access is exercised for each third-party.

This model supports two types of third-party, reflecting different regulatory and technical arrangements.

* A Licensed third-party holds its own regulatory licence, for example, as a third-party Provider under PSD2, and provides its own Open Banking certificates for Financial Institution connectivity.
* An Unlicensed third-party operates under your licence. No separate certificates are required, and the platform uses your credentials for provider connectivity.   

Both types are onboarded and managed through you as the Integrator. Third-parties do not call the platform directly.

The relationship that authorizes you to act on a third-party's behalf is established during onboarding. Once this relationship is in place, you can obtain access tokens scoped to that third-party and make API calls, creating consents, executing flows, and retrieving data, all attributed to the third-party. Consents and data are owned by the third-party. For reporting and billing purposes, activity can be aggregated at the Integrator level.

### How it Works {#how-it-works}

You authenticate with Mastercard Open Finance using your own credentials. When calling in the context of providing a service to a third party, include the third party's ID in the token request using the X-On-Behalf-Of header. Mastercard Open Finance validates the relationship and issues an access token scoped to the third-party, with an actor claim identifying you as the Integrator. You then use this token --- together with the third-party's Application ID in the X-Application-Id header --- to create consents, execute flows, and access data on their behalf.

1. The Integrator calls `POST /oauth2/tokens`.

         Header: X-On-Behalf-Of: <indirect_client_id> 

         Body:   client_credentials grant with private_key_jwt + DPoP 

2. Mastercard Open Finance validates the relationship and then issues an access token.

         Token payload: 

         { 

           "sub": "<indirect_client_id>", 

           "act": { "sub": "<integrator_client_id>" } 

         }

3. The Integrator initiates API calls (for example, `POST /consents`, `GET /accounts`)

         Header: Authorization: Bearer <access_token> 

         Header: X-Application-Id: <indirect_client_application_id> 

### Getting Started {#getting-started}

##### Integrator Onboarding {#integrator-onboarding}

Complete these steps once when setting up your integration:

* Provide your company legal name, primary and technical contact details, and countries of operation.
* Provide a TLS certificate from an accepted certificate authority.
* Receive your identifiers from the Delivery team: Client ID, Application ID, and Use Case Configuration IDs.

##### Third-party Onboarding {#third-party-onboarding}

Repeat these steps for each third-party you wish to serve:

* Provide the third-party's legal name, type (licensed or unlicensed), countries of operation, and required products or use cases.
* For licensed third-parties only, provide Open Banking certificates for Financial Institution connectivity, either through a custom signing service or Azure Key Vault.
* Receive the third-party's identifiers: Client ID and Application ID.

Unlicensed third-parties operate under your licence. No additional certificates are required.

##### Requesting an Access Token when Providing a Service to a Third-Party {#requesting-an-access-token-when-providing-a-service-to-a-third-party}

To obtain an access token scoped to a third-party, call the token endpoint with your credentials and the third-party's ID.

**Step 1 --- Prepare the Token Request**

Call `POST /oauth2/tokens HTTP/1.1`

    Host: auth.openbanking.mastercard.eu 

    X-On-Behalf-Of: <indirect_client_id> 

    DPoP: <dpop_jwt> 

    Content-Type: application/x-www-form-urlencoded 

    grant_type=client_credentials 

    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer 

    &client_assertion=<integrator_private_key_jwt> 

    &scope=consents:create 

|      **Field**      |                              **Description**                               |
|---------------------|----------------------------------------------------------------------------|
| `X-On-Behalf-Of`    | The third-party's ID --- identifies which third-party this request is for. |
| `client_assertion ` | A signed JWT using your private key. The sub-claim must be your Client ID. |
| `DPoP`              | A DPoP proof JWT bound to this specific request.                           |
| `scope`             | The requested scope, for example `consents:create` or `ob_data`.           |

**Step 2 --- Interpret the Response**

The access token is a JWT with this structure.

| **Claim** |       **Value**        |                    **Description**                    |
|-----------|------------------------|-------------------------------------------------------|
| `sub`     | `<indirect_client_id>` | The third-party on whose behalf the token was issued. |
| `act.sub` | `<indirect_client_id>` | You, the Integrator that requested the token.         |
| `scope`   | `Requested scope`      | The permissions granted.                              |

Note: Cache access tokens per third-party and monitor the `expires_in` value. Request a new token before the current one expires to avoid interruptions. Do not reuse tokens across third-parties.

#### Using the API in a Third-Party Context {#using-the-api-in-a-third-party-context}

Once you have an access token, include it as a Bearer token in API requests. Always include the third-party's Application ID.

#### Creating a Consent when Providing a Service to a Third-Party: {#creating-a-consent-when-providing-a-service-to-a-third-party}

Call `POST /consents HTTP/1.1`

    Host: api.openbanking.mastercard.com 

    Authorization: Bearer <access_token> 

    X-Application-Id: <indirect_client_application_id> 

    Content-Type: application/json 

     

    { "..." } 

#### Retrieving Accounts when Providing a Service to a Third-Party: {#retrieving-accounts-when-providing-a-service-to-a-third-party}

Call `GET /accounts HTTP/1.1`

    Host: api.openbanking.mastercard.com 

    Authorization: Bearer <consent_scoped_access_token> 

    X-Application-Id: <indirect_client_application_id> 

These headers are required on all API calls made in a third-party context.

|     **Header**     |             **Value**              | **Required** |
|--------------------|------------------------------------|--------------|
| `Authorization`    | `Bearer <access_token>`            | Yes          |
| `X-Application-Id` | `<indirect_client_application_id>` | Yes          |

#### Licensed and Unlicensed Third-Parties {#licensed-and-unlicensed-third-parties}

The intermediated access model accommodates both types of third-party, with differing regulatory and technical requirements.

|             **Aspect**             |           **Licensed third-party**           |     **Unlicensed third-party**      |
|------------------------------------|----------------------------------------------|-------------------------------------|
| Regulatory status                  | Holds own licence (for example, PSD2 TPP)    | Operates under your licence         |
| Certificates                       | Own Open Banking certificates required       | No additional certificates          |
| Financial Institution connectivity | Platform uses the third-party's certificates | Platform uses your certificates     |
| Onboarding                         | Certificate provisioning required            | Streamlined --- no certificate step |

### Best Practices {#best-practices}

* Credential security: Store your OAuth private keys in a secure vault (HSM recommended). Never share your credentials with third-parties.
* Token management: Cache access tokens per third-party. Tokens are third-party-specific. Do not reuse tokens across third-parties. Implement token refresh before expiration.
* Identifier tracking: Maintain a mapping of third-party business identifiers to Mastercard Client IDs. Store Application IDs alongside Client IDs for each third-party.
* Accountability and intermediation: Third-parties do not interact with the platform directly. All API calls are made by you, the Integrator, acting on each third-party's behalf. You are responsible for ensuring that access is exercised appropriately and within the scope authorized by each third-party.

### Next Steps {#next-steps}

Now that you understand the intermediated access model, explore these sections to continue your integration:

* [API Authentication](https://developer.mastercard.com/open-finance-data/documentation/api-basics/index.md) for details on key generation, JWT signing, and token management.
* [API Reference](https://developer.mastercard.com/open-finance-data/documentation/api-reference/index.md) for the full endpoint specification.
* [Use Cases](https://developer.mastercard.com/open-finance-data/documentation/use-cases/index.md) for examples of what you can build with Mastercard Open Finance.   

Contact [Mastercard support](mailto:openbankingeu_support@mastercard.com) to begin Integrator and third-party registration.