Backstack - Networks

Existing accounts have the capability to create child accounts for B2B relationships, including revenue sharing options.

How it works

Parent accounts send invitations to child accounts via system-generated emails for activation. These emails contain a tokened link that directs the child account to your activation page. You promptly request the API to establish the networked relationships using the email token. The API creates the necessary entities and emails instructions to the new account user for logging in.

Images

Prerequisites

The application must have the network and login URLs defined in the Backstack dashboard settings. These URLs serve as base endpoints for the links provided in system-generated emails.

Defining networks

Networks operate on a domain basis and are configured through the Backstack dashboard. Parent domain accounts have the ability to create child accounts in subordinate domains.

Images

Create network invitation

When a parent account initiates a networked relationship, the process begins by sending a system-generated email to the child account for activation. This network invitation includes a link to your activation page with a token in the request.

Create a page for an existing account to provide the information below. Use the enumerated domains and the enumerated countries (optional) to create dropdowns for selecting those values.

Request

POST /v1/network/initiate
{
  "domain_id": "dom_1234567890",
  "email": "j.doe@acme-corp.com",
  ...
}

Parameter	Type	Value
`domain_id`	Required string	The domain ID the child account will be created under.
`country_id`	Optional string	The country ID of the child account. If empty, the country_id of the parent account will be used.
`email`	Required string	The email address of the invitation recipient.
`fee_proposed`	Optional decimal	The percentage of revenue generated by the system that the parent account intends to collect from the child account. (Only available if the network is configured for monetization.)

Response

The Network Invitation object.

// network invitation object
{
  "id": "nwi_1234567890",
  "created": 1693341407,
  "domain_id": "dom_1234567890",
  "fee_proposed": 2.5,
  "email": "jdoe@acme.com",
  "expires": 1693514207,
  "status": "expired"
}

Update network invitation

todo

Accept network invitation

Create a landing page for the child account to activate the network, and provide the page URL in your dashboard settings.

The link provided in the initiation email will direct the user to this page with a token in the request. Post the token to the API, then inform the user that an email with log in instructions has been sent.

You should check for errors after submitting the token to the API. The token is time-sensitive and could be expired.

Request

POST /v1/network/activate/:token

Include the token provided in the request for your activation page in the API request URL.

Response

The newly created account object.

// account object
{
  "id": "acc_1234567890",
  ...
  "domain_id": "dom_1234567890",
  "version_id": "ver_1234567890",
  ...
}

Update account network

todo

The Network Invitation object

// network invitation object
{
  "id": "nwi_1234567890",
  "created": 1693341407,
  "domain_id": "dom_1234567890",
  "fee_proposed": 2.5,
  "email": "jdoe@acme.com",
  "expires": 1693514207,
  "status": "expired"
}

Property	Type	Description
`id`	String	The ID of the invitation.
`created`	Integer	The timestamp the invitation was created.
`domain_id`	String	The ID of the domain the account will be created under.
`fee_proposed`	Decimal	The percentage of revenue generated by the system that the parent account intends to collect from the child account.
`email`	String	The email address to which the invitation is being sent.
`expires`	Integer	The timestamp the invitation will expire.
`status`	String	The status of the invitation. Valid values are `active` (the account was created), `pending` and `expired`.

The Network object

todo