Skip to content

Networks

DANGER

This document has not been updated since version 0.0.3 and is not ready for production. It will be updated before version 1.0 of the project is released.

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 domains data in the app-schema and the enumerated countries (optional) to create dropdowns for selecting those values.

Request

sh
POST /v1/network/initiate
{
  "domain_id": "dom_1234567890",
  "email": "j.doe@acme-corp.com",
  ...
}
ParameterTypeValue
domain_idRequired stringThe domain ID the child account will be created under.
country_idOptional stringThe country ID of the child account. If empty, the country_id of the parent account will be used.
emailRequired stringThe email address of the invitation recipient.
fee_proposedOptional decimalThe 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.

json
// 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

sh
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.

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

Update account network

TODO

The Network Invitation object

json
// network invitation object
{
  "id": "nwi_1234567890",
  "created": 1693341407,
  "domain_id": "dom_1234567890",
  "fee_proposed": 2.5,
  "email": "jdoe@acme.com",
  "expires": 1693514207,
  "status": "expired"
}
PropertyTypeDescription
idStringThe ID of the invitation.
createdIntegerThe timestamp the invitation was created.
domain_idStringThe ID of the domain the account will be created under.
fee_proposedDecimalThe percentage of revenue generated by the system that the parent account intends to collect from the child account.
emailStringThe email address to which the invitation is being sent.
expiresIntegerThe timestamp the invitation will expire.
statusStringThe status of the invitation. Valid values are active (the account was created), pending and expired.

The Network object

TODO