Share A/S/F with existing user

Jane is an existing, authenticated user who opts to share access to one (or more) of their associated accounts or services with John. In this scenario, John is already a registered with his own Storefront Gateway User ID.

Note: The above flow diagram includes recommended APIs to retrieve additional user information, to make the actual front user experience a bit more clear and meaningful. Since the Process requires that the relevant Account (or Subscription or Feature), target User, and possibly target Group are all specified by their internal identifying numbers, then the client will likely need to make additional call against those Storefront Gateway entities and parse out the right details to show to the user.

Initial Request

Your client calls the Process Start API to initialize the Process:

**POST https://\{your.url\}/process/start/entitlementManagement.ShareASF.v1.0**
<no body>

Response: Specify the invitee, entities, and permissions

Storefront Gateway responds with a prompt to specify the invitee by their contact channel, and to specify the Account, Subscription, or Feature entitlement entities to share. The response also includes a list of applicable entity types for the client to specify:

**RESPONSE - body**
{
   "processId": "fbd2ce42-2ce9-4116-b701-5af45b2aae79",
   "processName": "entitlementManagement.ShareASF.v1.0",
   "stepName": "Prompt",
   "lastName": false,
   "output": {
      "validPermissions": [
         "consumption",
         "admin",
         "admin+consumption"
      ],
      "validTypes": [
         "account",
         "subscription",
         "feature"
      ]
   },
   "parameters": {
      "authnIdentifier": "user@example.com",
      "shareEntities": [
         {
            "entityType": "account",
            "entityId": 12345,
            "permission": "consumption"
         },
         {
            "entityType": "subscription",
            "entityId": 34567,
            "permission": "admin+consumption"
         }
      ]
   }
}

The accounts or services to share must be specified by the unique, internal id property on each Storefront Gateway entity. As this number is likely not known to the user, the client application should leverage the relevant APIs (e.g., GET /user/accounts API, or GET /user/subscriptions), in conjunction with this Process, to retrieve additional details stored on each entity, and then render them to the user. Note: The parameters object indicates what it needs from the client to continue its task. In this scenario, the values for each field in the object are generic and indicative of format (strings and integers), but not the specific exact values expected in the next request. In other words, the client should ignore the any sample values (e.g., “user@Example.com,” 12345, “consumption,”) in this response, and instead simply return the user’s selections (the invitee contact channel, each account or service – identified by the unique id field on the Storefront Gateway entity – and the permissions level).

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`output`	Object that contains data that the client can consume, retain, and use for additional operations.
`validUsers`	Array of Storefront Gateway Users that the current User has the right to perform account or service revocation. Each object in the list contains:
`userId`	The internal, unique identifier for the User entity.
`displayName`	The registered `firstName` and `lastName` of the User entity.
`sharedEntities`	Array of accounts, subscriptions, and features associated to the User entity. Only includes entities that the current user can revoke from this user.
`entityType`	The type of entity being shared (e.g. account, subscription).
`entityId`	The unique internal identifier on the entity.
`displayName`	Display name of the account or service, registered on the entity
`permission`	The permission type this user has on the entity .
`parameters`	Object that specifies the info this Process requires to continue its task.
`authnIdentifier`	The email address or mobile number of the desired invitee.
`sharedEntities`	Array of entites to be shared with the invitee. Each entity object includes:
`entityType`	The type of entity being shared (e.g. account, subscription).
`entityId`	The unique internal identifier on the entity.

Final Request: User Selections

The user provides the invitee’s email or mobile, and selects the account or service(s) that they want to share. Your client passes the user’s explicit selections to the Process using the Process Step API:

**PUT https://\{your.url\}/process/step**
{
   "processId": "fbd2ce42-2ce9-4116-b701-5af45b2aae79",
   "parameters": {
      "authnIdentifier": "john@example.com",
      "shareEntities": [
         {
            "entityType": "subscription",
            "entityId": 3786,
            "permission": "consumption"
         }
      ]
   }
}

Note: In this example, a single subscription is being shared with the target user. It is possible to share access to multiple entitlement entities in a single request, if applicable, by adding additional entries into the entities array. For example:

{
   "processId": "a1fbea6f-6462-4138-b297-484a9be74af1",
   "parameters": {
      "userId": 93612,
      "entities": [
         {
            "entityType": "subscription",
            "entityId": 3786,
            "permission": "consumption"
         },
         {
            "entityType": "subscription",
            "entityId": 3790,
            "permission": "consumption"
         },
         {
            "entityType": "feature",
            "entityId": 37901
            "perission": "consumption"
         },
      ]
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data requested in the previous Process response.
`authnIdentifier`	The email address or mobile number of the desired invitee.
`shareEntities`	Array of entities to be shared with the invitee user. Each entity object includes:
`entityType`	The type of entity being shared. Acceptable values are: - `account` - `subscription` - `feature`
`entityId`	The unique internal identifier (i.e., the `id` property) on the entity.
`permission`	The permission type set to grant the recipient on the selected entity. Acceptable values are: - `admin` - `consumption` - `admin+consumption`

Process Complete

The Process queries the Storefront Gateway datastore for the email address or mobile number provided by the user. In this scenario, the email or mobile is already registered on as an authentication identifier (authN ID) on an existing Storefront Gateway User ID. Therefore, the Storefront Gateway then performs the following back-end associations:

The invitee is added to the relevant group (i.e., the invitee’s Storefront Gateway User entity is associated to the Storefront Gateway Group entity that is used for the relevant Account/Subscription/Feature hierarchy)
The invitee’s Storefront Gateway User ID is associated to to specified Account(s), Subscription(s), and Feature(s).

These associations have an activating status until the invitee explicitly accepts or declines the invitation through the Accept or Decline Process. This ensures that the invitee cannot access any of the shared account(s) or service(s) until they explicitly accept. The following conditions apply:

If the invitee accepts, then that Process fully activates the associations.
If the invitee explicitly declines, Storefront Gateway removes the associations immediately.
If the invitee simply never opens the invitation, then Storefront Gateway automatically removes the associations after a length of time.

Storefront Gateway then sends an invitation message to the invitee, and the Process returns a 200 HTTP status:

**RESPONSE - body**
{
   "processId": "a1fbea6f-6462-4138-b297-484a9be74af1",
   "processName": "entitlementManagement.ShareASF.v1.0",
   "lastStep": true,
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.

Next Process

Storefront Gateway sends a notification message to the invitee’s email address or mobile number. The message contains a clickable redirect URL with a Storefront Gateway Action Token appended to the end of the link. The invitee will need to click the link, and that link redirects them back to a dedicated page of your client application that takes token value directly from the URL, and calls the [GET /session/token?token=\{token\}](c_sessionToken) API. This will trigger the Accept or Decline Process, wherein the invitee can explicitly accept or decline the access being offered. Parent topic:Share Access to an Account, Subscription, or Feature

Home

Introduction

For Merchants

For Resellers

Partner Ecosystem Management

Commerce Engine

Storefront Experience

APIs

Initial Request

Response: Specify the invitee, entities, and permissions

Final Request: User Selections

Process Complete

Next Process

​Initial Request

​Response: Specify the invitee, entities, and permissions

​Final Request: User Selections

​Process Complete

​Next Process

Initial Request

Response: Specify the invitee, entities, and permissions

Final Request: User Selections

Process Complete

Next Process