# B2B Token

In B2B scenarios, the customers frequently represent more than one company. They can belong to more than one legal entity that they act and make purchases on behalf of.\
Therefore, the storefront needs to identify which legal entity a user is acting on behalf of during each session to properly resolve the right data access and scope level.

Example use cases:

* Orders: The customer's assigned legal entity can be crucial for accessing orders information. B2B customers need to access their own orders, but also the orders assigned to their legal entity.
* Products availability: With customer segments, product visibility can become segment-based. Therefore, the endpoint responsible for retrieving products on the storefront has to return only these products that the customer has access to with the selected legal entity.

## Legal entity in authorization token

To ensure that the storefront properly reads a B2B customer's selected legal entity and determines the relevant access to resources, the authorization token generated by the [Customer Service](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#get-customer-tenant-refreshauthtoken) gets updated with the `legalEntityId` parameter.\
The token-based approach to pass the `legalEntityId` parameter guarantees that the relevant services use that information to retrieve relevant data. The `legalEntityId` header is injected in the requests.

{% hint style="warning" %}
Passing the `legalEntityId` parameter in the authorization token is the proper way to handle the B2B customer legal entity information across services.\
The token approach ensures a consistent user experience, and centralized security enforcement while enabling the required legal entity-based access control.
{% endhint %}

## How it works

{% stepper %}
{% step %}

#### Selection and verification

When a B2B customer logs in, they choose the specific legal entity they want to represent for that session. The Customer Service then verifies that the user is assigned to this selected entity.
{% endstep %}

{% step %}

#### Token generation

Upon verification, the [Customer Service](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-service/api-reference) issues a new refresh token that embeds the `legalEntityId` parameter.
{% endstep %}

{% step %}

#### Data access and scope

This updated token is passed to other services to determine the correct scopes and data visibility for the user. The `legalEntityId` header is injected into requests, ensuring the user only accesses relevant data, such as orders or segment-based product visibility tied to that specific legal entity.
{% endstep %}

{% step %}

#### Seamless switching

If the customer needs to change the legal entity they are acting on behalf of, they do not need to log in again. The storefront simply triggers the [Refreshing a customer token](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#get-customer-tenant-refreshauthtoken) endpoint to generate a new token based on the previous one, but with the updated `legalEntityId` information.
{% endstep %}
{% endstepper %}

The diagram shows how the legal entity information is fetched and passed:

{% @mermaid/diagram content="---
config:
layout: fixed
theme: base
themeVariables:
primaryColor: '#DDE6EE'
primaryBorderColor: '#4C5359'
actorBkg: '#DDE6EE'
actorBorder: '#4C5359'
actorLineColor: '#4C5359'
signalColor: '#E86C07'
signalTextColor: '#7B8B99'
background: transparent
-----------------------

sequenceDiagram
participant User
participant Storefront
participant CustomerService as Customer Service
participant CustomerManagementService as Customer Management Service

```
User ->> Storefront: Login request
Storefront ->> CustomerService: Login request
CustomerService -->> Storefront: Generate and return initial token

Storefront ->> CustomerService: Fetch /me
CustomerService -->> Storefront: Return user info

User ->> Storefront: Select legal entity
Storefront ->> CustomerService: Refresh the token with selected legal entity
CustomerService ->> CustomerManagementService: Validate user access
CustomerManagementService -->> CustomerService: Validation success
CustomerService -->> Storefront: Generate and return new token" %}
```

{% hint style="warning" %}
Find out more about the Customer Service and token generation in the API reference [Customer Service (Customer Managed)](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-service/api-reference) documentation.
{% endhint %}