> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/standard-practices/b2btoken.md). # B2B Token The B2B Token embeds a customer’s selected legal entity in their authorization token, enabling consistent access control and data visibility without re-login. 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](/api-documentation/api-guides/companies-and-customers/customer-service/api-reference.md) 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 --- 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)](/api-documentation/api-guides/companies-and-customers/customer-service/api-reference.md) documentation. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-documentation/standard-practices/b2btoken.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.