7.8. Registering a new company

Registering an existing company, already available in the 3rd-party system is a semi-automatic process. The user will need to be redirected to the SmartBL website to finish the registration process.

This is required for two reasons:

  • BDTS is a global platform, as it relies on the global blockchain. As such, even whitelabelled solutions do not exist in their own walled gardens. The consequence is that the company that the 3rd-party system is trying to register, might already exist on the platform. As there is no simple world-wide method of determening the company uniqueness, this must be left to the user.
  • The user will need to provide a company's blockchain key. As the key is always stored with the user and should never leave his system, the only good way of doing this is interactivly -- by user visiting the web site and providing their key.

From the user's perspective this is similar to how Log in with Facebook or Login in with Google buttons on the web function today.

The flow is as follows:

  • A third party system creates a registration token and receives a registration_url and redirects the user to it.
  • The user completes the registration and is redirected to redirect_url which is provided by the third party system. If the user is already registered, she is provided with a dialog where she can allow the third party system to manage her account.

Example

7.8.1. Submit company details

Use the registration token endpoint to submit the company details.

cat << EOF > company.json
{
  "legal_business_name": "A Salt and Battery Ltd.",
  "branch_office": null,
  "business_address": "221b Baker Street",
  "business_postal_code": "NW1 6XE",
  "business_city": "London",
  "business_state": null,
  "vat_id_number": "UK2718281828,
  "business_website": "http://www.sherlock-holmes.co.uk/",
  "user_first_name": "Sherlock",
  "user_last_name": "Holmes",
  "user_department": null,
  "user_position": null,
  "user_telephone": null,
  "business_contact_email": "[email protected]",
  "date_of_formation": "2019-03-19",
  "billing_attn_to": null,
  "billing_company_name": "A Salt and Battery Ltd.",
  "billing_address": "221b Baker Street",
  "billing_postal_code": "NW1 6XE",
  "billing_city": "London",
  "billing_country": "UK",
  "billing_state": null,
  "is_allowed_to_issue_bl": false,
  "is_release_agent": false,
  "redirect_url": "https://3rd-party-registration-finish.example.org?registrationId=iddqd"
}
EOF

curl \
   -H 'Authorization: Bearer 3gjCob2ryo6WvYQtmAuwwEBfuvQkrr' \
   -X POST
   -H "Content-Type: application/json" \
   --data @company.json \
   https://app.smartbl.io/api/v1/third-party/registration-token/

The result of this post will be a redirect_url which is used to redirect the user to the SmartBL site.

7.8.2. Redirect the user to back to 3rd-party site

User is redirected to SmartBL website where she needs to either:

  • Login if she already has an account,
  • or Register (details are prefilled from the previous post) to used the SmartBL platform.

7.8.3. 3rd-party system is authorized to access the company account

The 3rd-party system is given permission to access the company account. The 3rd-party system is now listed under "Connected applications" on the company's account.

Note

Authorized user may revoke the permission of the 3rd-party system at any time. If such is the case, all queries from the 3rd-party system to BDTS will start returning an error.

It's easy enough to reconnect such system in case the permission was revoked by mistake -- the user simply needs to go through the registration produce (as explained in this document) again.

7.8.4. Redirect back

The user is redirected back to the 3rd-party system, to the URL specified in the redirect_url.