The most flexible way to resell Hivelocity services is to use our REST API. Our business is run by the same APIs you have access to in this documentation. The sky is the limit in the services you can offer your customers.

Single vs Multi Account

When integrating with the API you have two options: single and multi client integrations. All inventory & pricing remains the same regardless of the type of API integration. The difference is how the services and data are isolated.

Single Account

In the single account model you have one client account that contains all the devices that your customer orders. In this model, when you login to the Hivelocity portal. You will see a list of all devices owned by all of your clients and will handle all ticketing and billing of your entire reseller business from the portal.

Pros

• You can mange your entire reseller busisness from one portal.
• Adding a payment method to this one account pays for all invoices.
• All support tickets are under one roof.

Cons

• Your software integration must track which devices, invoices, tickets, and other services belong to each customer.

Getting Started: Single Account Integration

Single account integration is straight forward. Ensure you have completed all Prereqs and understand how to Authenticate your API requests. Then you can make API calls as normal to collect inventory and deploy servers.

Multi Account

With the multi account model you have one client account for each of your individual customers. In this model each individual customer's services are isolated in their own individual client accounts. When you login to your client account you won't see any of your customer's services or data. You would have to to login to their accounts individually to see their services. Additinoally, your customer's login will be disabled for our portal.

Pros

• Each of your customer's devices, invoices, payment method, etc are isolated to a single client account.
• Easier to tie back into billing systems as you can request invoices for specific customers.
• Your software integration only has to track which client account belongs to your customer.
• Your API key can be configured to only affect one client account at a time - protecting you from human error and bugs.

Cons

• Extra API calls to authenticate with the targeted client account.
• Multiple client accounts to login to for managing tickets.

Getting Started: Multi Account Integration

We need to manually enable your client account for Multi Account API integration. Please reach out to [email protected] or fill out our partnership application form to have your account enabled.

Once your account is enabled, ensure you have completed all API Prereqs and understand how to Authenticate your API requests.

Controlled Client Accounts

The isolated client accounts for your customers are called controlled clients. Because their accounts are controlled by your primary client account. Whenever a customer signs up for your platform you want to create a unique controlled client for that customer.

Creating a new controlled client

Using the API key from your primary client account make a POST /account/controlled-client request. This will create a new controlled client account and return the id of the account.

curl --request POST \
     --url https://core.hivelocity.net/api/v2/account/controlled-client \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header "X-API-KEY: $API_KEY" \
     --data '
{
    "email": "[email protected]",
    "company": "Your Customer",
}
'

👍

Use your primary client's email address for each controlled client.

If you want to make it easier to manage multiple accounts in the Hivelocity portal, then always use the same email address when creating a controlled account. When you authenticate with an email address that is the owner of multiple accounts you get a searchable account picker on authentication as well as a switch account button in the portal that does not require re-authentication.

❗

Save the client ID

The returned client ID is the unique identifier of the controller client account. You want to save it in your database with a relation the main customer entity in your sofware.

Making requests as a controlled client

Your primary client account's API Key can execute any v2 endpoint as if it were the controlled client, isolating those calls to the controlled client's account. This is done by passing the url a controlledClientId query arg.

For example, the below call will deploy a server underneath the controlled client 35476.

curl -X 'POST' \
  'https://core.hivelocity.net/api/v2/bare-metal-devices/?controlledClientId=35476' \
  -H 'accept: application/json' \
  -H "X-API-KEY: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "period": "hourly",
  "productId": 584,
  "hostname": "server.example.com",
  "locationName": "TPA1",
  "osName": "Ubuntu 20.x"
}'

Alternatively, a safer way of making API calls is to request the Controlled Client's API key from GET /token.

curl --request GET \
     --url https://core.hivelocity.net/api/v2/token/?controlledClientId=35476 \
     --header 'Accept: application/json' \
     --header "X-API-KEY: $API_KEY"

Then use the returned token as the X-API-Key authentication header for all subsequent calls. This will also isolate all subsequent calls to the target controlled client account.

Deactivating a controlled client

If you need to deactivate a controlled client, make a PUT /account/controlled-client request with its ID as the client_id in the request body.

curl --request PUT \
     --url https://core.hivelocity.net/api/v2/account/controlled-client \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header "X-API-KEY: $API_KEY" \
     --data '
{
    "client_id": "35476
}
'

🚧

Deactivated clients cannot be re-activated

Only deactivate a client if you are sure they no longer need their services. The account will be permanently unavailable after this call. Usually, it is better to flag the account as deactivated in your own software.

Getting a list of your controlled clients

Send a GET /account/controlled-client request.

curl --request GET \
     --url https://core.hivelocity.net/api/v2/account/controlled-client \
     --header 'Accept: application/json' \
     --header "X-API-KEY: $API_KEY"