Appearance
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.
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.
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",
...
}
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.
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"
}
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