The onboarding server allows makers to manage their hotspot production and permit hotspot customers to onboard them to the blockchain.
Before running the following commands, make sure to have a running postgres db instance.
- clone the repo
- run
yarn install - initialize the database with
yarn db:create - run the migrations with
yarn db:migrate - run
yarn task src/tasks/create_maker.jsand follow the prompts to create or import a Maker record - run the dev server with
yarn dev - the dev server will be accessible at
localhost:3002
When running in production, make sure to set the following env vars to secure random values:
| Environment Variable | Description | Example |
|---|---|---|
| KEYRING | JSON keyring object | {"1":"2xNJEZvMlr99yPqGfh0sa7pO7j1tH73RTU9qJwwi4bs="} |
| KEYRING_SALT | Additional entropy for keyring encryption | WmcKZ46ciIZqTvXm9TMd5V63b8k6iw/tVkcv/qEI0KU= |
(add more important vars here)
The recommended way of generating secure secrets is:
dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64 -A
Refer to https://github.com/fnando/keyring-node for additional details about how the at-rest encryption with keyring works.
In production it is recommended to enable rate limiting to prevent nefarious users from scraping or brute forcing the APIs. Rate limiting relies on Redis to store IP addresses and request counts. Redis connection info is supplied through a REDIS_URL env var.
The onboarding server is configured to run on Heroku out of the box. It will use the nodejs buildpack, and comes with a Procfile that defines the web resource command as npm start. Additionally, the free Heroku Redis add-on can be installed and will automatically be picked up by the rate limiter.
Admin tasks can be run on Heroku like so: heroku run yarn task src/tasks/create_maker.js
The following tasks are included for managing admin functionality of the onboarding server:
yarn task src/tasks/create_maker.js
Creates a Maker account taking name, location nonce limit and optionally an exported wallet entropy string. You can also choose to create a Maker API token for the newly created Maker.
yarn task src/tasks/create_token.js
Creates a Maker API token for the selected Maker.
yarn task src/tasks/export_maker.js
Exports the unencrypted wallet entropy seed to be imported into another onboarding server instance.
- Base route:
/api/v2
With all requests, include an authorization header where the value is your public token and private token joined with a colon (:). For example:
curl --location --request GET 'https://onboarding.example.com/api/v2/hotspots' \
--header 'authorization: pk_INSERT_REST_OF_PUBLIC_TOKEN:sk_INSERT_REST_OF_SECRET_TOKEN'
With all POST and PUT requests that contain a body, include the Content-Type: application/json header. For example:
curl --location --request POST 'https://onboarding.example.com/api/v2/hotspots' \
--header 'Authorization: auth_tokens_here' \
--header 'Content-Type: application/json' \
--data-raw '{
"macWlan0": "example mac"
}'
This API allows a Maker to create and manage their Hotspots.
Returns all Hotspots that a Maker has created in a paginated fashion. Page number and size can be controlled by optional url params.
GET /hotspots
| Param | Required | Default Value | Description |
|---|---|---|---|
| page | no | 0 | Page number used to paginate index of Hotspots |
| pageSize | no | 100 | Number of Hotspots returned per page |
GET /hotspots?page=5&pageSize=100
Returns an individual Hotspot identified by its ID.
GET /hotspots/:id
GET /hotspots/123
Searches for a Hotspot based on any of its attributes.
GET /hotspots/search
| Param | Required | Default Value | Description |
|---|---|---|---|
| onboardingKey | no | NULL | A unique key that is used to identify a Hotspot for onboarding |
| macWlan0 | no | NULL | Mac address of the wifi component |
| macEth0 | no | NULL | Mac address of the ethernet component |
| rpiSerial | no | NULL | Serial number of the Raspberry Pi unit |
| heliumSerial | no | NULL | Serial of the Helium unit |
| batch | no | NULL | A string used to identify manufacturing batches |
| publicAddress | no | NULL | The b58 public address of the Hotspot that was onboarded |
GET /hotspots/search?macWlan0=examplemac
Creates a new Hotspot entry. Hotspot details should be provided as a json object in the body of the POST request.
POST /hotspots
| Param | Required | Default Value | Description |
|---|---|---|---|
| onboardingKey | no | NULL | A unique key that is used to identify a Hotspot for onboarding |
| macWlan0 | no | NULL | Mac address of the wifi component |
| macEth0 | no | NULL | Mac address of the ethernet component |
| rpiSerial | no | NULL | Serial number of the Raspberry Pi unit |
| heliumSerial | no | NULL | Serial of the Helium unit |
| batch | no | NULL | A string used to identify manufacturing batches |
POST /hotspots
request body:
{
"onboardingKey": "example-onboarding-key",
"macWlan0": "22:98:17:a3:03:90",
"macEth0": "e4:0b:59:88:27:5f",
"rpiSerial": "example-rpi-serial",
"heliumSerial": "example-helium-serial",
"batch": "example-batch"
}Updates attributes of a Hotspot. NOTE: once a Hotspot has been onboarded and the publicAddress field set, it becomes immutable and cannot be changed or deleted by the Maker.
PUT /hotspots
| Param | Required | Default Value | Description |
|---|---|---|---|
| onboardingKey | no | NULL | A unique key that is used to identify a Hotspot for onboarding |
| macWlan0 | no | NULL | Mac address of the wifi component |
| macEth0 | no | NULL | Mac address of the ethernet component |
| rpiSerial | no | NULL | Serial number of the Raspberry Pi unit |
| heliumSerial | no | NULL | Serial of the Helium unit |
| batch | no | NULL | A string used to identify manufacturing batches |
PUT /hotspots/123
request body:
{
"rpiSerial": "updated-rpi-serial",
"heliumSerial": "updated-helium-serial",
}Deletes a Hotspot record identified by ID. NOTE: once a Hotspot has been onboarded and the publicAddress field set, it becomes immutable and cannot be changed or deleted by the Maker.
DELETE /hotspots/:id
| Param | Required | Default Value | Description |
|---|---|---|---|
| onboardingKey | no | NULL | A unique key that is used to identify a Hotspot for onboarding |
| macWlan0 | no | NULL | Mac address of the wifi component |
| macEth0 | no | NULL | Mac address of the ethernet component |
| rpiSerial | no | NULL | Serial number of the Raspberry Pi unit |
| heliumSerial | no | NULL | Serial of the Helium unit |
| batch | no | NULL | A string used to identify manufacturing batches |
DELETE /hotspots/123