> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Share Access to an Account, Subscription, or Feature
This Process enables an end to invite another Storefront Gateway user to share access to an account or service (represented by a Storefront Gateway Account, Subscription, or Feature entity).
## Multiple Process Orchestration
Many user journeys are facilitated by a single Business Process. However, there are some cases where Storefront Gateway orchestrates and links two or more Processes to complete a given journey.
## Service Sharing through Group Association
Storefront Gateway enables best-in-class account and service entitlement delegation (i.e., sharing access) by way of Storefront Gateway Groups and associations. Storefront Gateway Groups serve as a connective entity between Storefront Gateway Users and shared services (including communications and digital service providers) that are provisioned as Storefront Gateway Account, Subscription, and Feature entitlement entities.
With each user, whether they own or are shared access to a service, comes a unique set of personalized historical user data. User preferences and service consumption habits (e.g., your viewing history in a streaming TV service) can be captured on an individual basis, and then leveraged to market and deliver value-added services to those same users as they inevitably move on to their own purchases.
**How it works (Storefront Gateway entities and associations)**
When a user [associates an external account](c_associateBillingAccountV2) (and any services under that account) to their User ID:
* Storefront Gateway maps external customer data to a Storefront Gateway Account/Subscription/Feature (A/S/F) hierarchy.
* The user then selects a group for the A/S/F.
* If the Storefront Gateway User is not associated to an applicable Storefront Gateway Group, the system creates one.
* Storefront Gateway associates the Storefront Gateway User to the Group, and designates them as the "Primary User."
* Storefront Gateway associates the User to every entity in the entire A/S/F hierarchy
Storefront Gateway then associates the selected (or create) Storefront Gateway Group to every entity in the A/S/F hierarchy.
The Group's Primary (or Admin User, set by the Primary) can then add other Users, and assign Admin (manage and consumption) or Regular (just consumption) entitlements to the Account, or specific Subscriptions and Features under the Account, on a granular per-user per-service basis.
**About Groups**
* In many households, multiple accounts are added to a single group owned by the "head of the household" such as a parental figure.
* To access any shared account or service, a Regular User must both **be in the group** (i.e., their Storefront Gateway User entity must be associated to the Storefront Gateway Group entity) **and** they must **be granted permissions by the group Primary** (i.e., their User entity must be directly associated to the relevant shared Account, Subscription, or Feature). Simply being in a group does not grant any access to any of that group's associated accounts or services.
* If the invitee is not a Storefront Gateway User, the **Share Account or Service** Process creates a new User entity, and the [Accept or Decline](c_acceptDeclineServiceInvitation) Process, when invoked by the invitee, finishes the user onboarding and activation.
* A Regular User entity's associations do not cascade up or down the A/S/F hierarchy. For example, if a Primary User adds another User to their Group, and assigns the Regular User entitlements (consumption only) to the Subscription entity, then that Regular User does not automatically have access to any of the Account "above" the Subscription, or Features "under" it. In other words, a Group's Primary User can grant fine-grain entitlements to different accounts and services for other Regular Users in the Group.
## Process Flow
This flow describes the Process at a high level.
**Preconditions**
* The user is currently authenticated in Storefront Gateway, and in their Identity profile.
* The user has at least one associated account or service (represented by Storefront Gateway Account/Subscription/Feature entitlement entities), and they are the associated Group's Primary User.
**Basic Flow**
1. The user authenticates, navigates to the account/service management section of your application UI, and selects to share an account or service.
2. The client application invokes the Process, and Storefront Gateway responds with a prompt to specify:
* the target invitee's contact channel
* the target Account, Subscription, or Feature entitlement entity to share
* the type of access permissions that the current User wants to grant to the invitee
3. The client renders the prompt to the user.
**Note:** Depending on the UI implementing the Process, this might look like an option to add other users to a service or service group. For example, a user might see **Add Users to your Stream TV Group** or simply **Share Access to your Stream TV**. The user group does not necessarily need to be explicitly defined for the end user experience, though it is an underlying component on the Storefront Gateway back end.
4. The user specifies the invitee by their email address or mobile number.
5. The user specifies the account or service they want to share with the invitee.
6. The user also sets the permissions for each individual account or service to be shared. This Process accepts the following permission types:
* **Admin** — The invitee can manage the account or service, but they cannot consume.
* **Consumption** — The invitee can consume the service, but they cannot manage it.
* **Admin & Consumption** — The invitee can manage and consume the account or service.
**Note:** Once the client submits the user's choices, Storefront Gateway checks how many User entities are already associated to the Group. If the Group has already reached the maximum number of Users (controlled by the **Group Size Limit** setting), then the Process ends.
7. The Process searches for any existing Storefront Gateway User with the invitee's email or mobile number.
* If no Storefront Gateway User already exists, then Storefront Gateway creates a new User ID (i.e., User entity) with the invitee's email/mobile.
* The email/mobile is stored on the new User entity as an attribute, and registered as the User's authentication identifier (authN ID) for sign-in purposes.
* Storefront Gateway creates both the User ID and its authN ID with an **`activating`** status.
* The invitee will user complete onboarding with the [Accept/Decline](c_acceptDeclineServiceInvitation) Process.
8. Storefront Gateway adds the invitee's User entity to the Group. Storefront Gateway also associates the User entity to the target A/S/F entitlement entities.
* These associations are created with an **`activating`** status.
* Storefront Gateway will fully activate these associations when the invitee invokes the [Accept/Decline](c_acceptDeclineServiceInvitation) Process and explicitly accepts the invitation.
9. Storefront Gateway sends an invitation out to the invitee's mobile number or email address.
* If the invitee never clicks the invitation link, Storefront Gateway eventually removes all associations.
* If the invitee was a new user, and they never open the invite, then Storefront Gateway will also eventually destroy eventually the unactivated User entity.
**Post-conditions**
* The invitee receives an invitation through email or SMS, depending on the channel type the inviting user supplied.
**Possible or Common Errors**
* The specified Account, Subscription, or Feature ID was not found.
* The specified permissions does not fall into pre-defined options (e.g., Admin, Consumption).
* The provided email or mobile is not in a valid format.
* The email or mobile field cannot be empty.
* The Group is already at maximum User capacity.
* The current user is not a Primary or Admin of the User Group, and therefore not allowed to invite others.
## App Settings
Certain aspects of the Process' behavior are controlled by configurable system settings. Your organization can manage these and other settings in the Storefront Gateway Admin web application.
| Settings | Default Setting | |
| - | - | - |
| **Token (long-form) Expiration** | Determines the number of minutes before the invitation link, sent to the invitee, expires. | 10080 minutes (7 days) |
| **Valid Email Pattern** | Defines the logic for an acceptable email format. | `.+@.+\..+` |
| **Valid Mobile Pattern** | Defines the logic for an acceptable mobile number format. | `^\(?([0-9]{3})\)?[-.\s]?([0-9]{3})[-.\s]?([0-9]{4})$` |
| **Group Size Limit** | Limits the number of User entities that can be added to a Group. | 10 |
**Note:** There is an additional limit that can optionally be set directly on Storefront Gateway Account, Subscription, and Feature entitlement entities. A `maxUser` attribute can control the maximum number of Users that can be associated to those entities, independent of the Group Size Limit.
Unlike the Group Size Limit, the `maxUser` attribute is typically configured once during the initial onboarding and integration between your organization and Storefront Gateway. It does not technically function in the same way as Storefront Gateway's application settings.
## User Journey Diagram
This diagram illustrates the standard user journey using the **Accept or Decline** Process.
## Use Cases
The following use cases provide guided API walk-throughs of this Process for client developers:
* [Share A/S/F access with an existing user](c_useCaseShareASFexisting)
* [Share A/S/F access with a new user](c_useCaseShareASFnew)
* [Share A/S/F access errors](c_shareASFerrors)
* **[Share A/S/F with existing user](c_useCaseShareASFexisting)**
* **[Share A/S/F with new user](c_useCaseShareASFnew)**
* **[Share A/S/F access errors](c_shareASFerrors)**
**Parent topic:**[Account Association & Management Processes](../images/c_accountProcesses)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.